@c Copyright (C) 2000-2023 Free Software Foundation, Inc.
@c This file is part of GNU Modula-2.

@c Permission is granted to copy, distribute and/or modify this document
@c under the terms of the GNU Free Documentation License, Version 1.2 or
@c any later version published by the Free Software Foundation.
@menu
* Base libraries::Basic M2F compatible libraries
* PIM and Logitech 3.0 Compatible::PIM and Logitech 3.0 compatible libraries
* PIM coroutine support::PIM compatible process support
* M2 ISO Libraries::ISO defined libraries
@end menu

@c ============================================================

@node Base libraries, PIM and Logitech 3.0 Compatible, , Libraries
@section Base libraries

@c README.texi describes the pim libraries.
@c Copyright @copyright{} 2000-2023 Free Software Foundation, Inc.
@c
@c This is part of the GM2 manual.
@c For copying conditions, see the file gcc/doc/include/fdl.texi.

These are the base libraries for the GNU Modula-2 compiler.  These
modules originally came from the M2F compiler and have been cleaned up
and extended.  They provide a basic interface to the underlying
operating system via libc.  They also include a number of libraries to
allow access to compiler built-ins. Perhaps the largest difference to
PIM and ISO libraries is the @code{DynamicString} module which
declares the type @code{String}.  The heavy use of this opaque data
type results in a number of equivalent modules that can either handle
@code{ARRAY OF CHAR} or @code{String}.

These modules have been extensively tested and are used throughout
building the GNU Modula-2 compiler.
@menu
* gm2-libs/ASCII::ASCII.def
* gm2-libs/Args::Args.def
* gm2-libs/Assertion::Assertion.def
* gm2-libs/Break::Break.def
* gm2-libs/Builtins::Builtins.def
* gm2-libs/COROUTINES::COROUTINES.def
* gm2-libs/CmdArgs::CmdArgs.def
* gm2-libs/Debug::Debug.def
* gm2-libs/DynamicStrings::DynamicStrings.def
* gm2-libs/Environment::Environment.def
* gm2-libs/FIO::FIO.def
* gm2-libs/FormatStrings::FormatStrings.def
* gm2-libs/FpuIO::FpuIO.def
* gm2-libs/GetOpt::GetOpt.def
* gm2-libs/IO::IO.def
* gm2-libs/Indexing::Indexing.def
* gm2-libs/LMathLib0::LMathLib0.def
* gm2-libs/LegacyReal::LegacyReal.def
* gm2-libs/M2Dependent::M2Dependent.def
* gm2-libs/M2EXCEPTION::M2EXCEPTION.def
* gm2-libs/M2LINK::M2LINK.def
* gm2-libs/M2RTS::M2RTS.def
* gm2-libs/MathLib0::MathLib0.def
* gm2-libs/MemUtils::MemUtils.def
* gm2-libs/NumberIO::NumberIO.def
* gm2-libs/OptLib::OptLib.def
* gm2-libs/PushBackInput::PushBackInput.def
* gm2-libs/RTExceptions::RTExceptions.def
* gm2-libs/RTint::RTint.def
* gm2-libs/SArgs::SArgs.def
* gm2-libs/SCmdArgs::SCmdArgs.def
* gm2-libs/SEnvironment::SEnvironment.def
* gm2-libs/SFIO::SFIO.def
* gm2-libs/SMathLib0::SMathLib0.def
* gm2-libs/SYSTEM::SYSTEM.def
* gm2-libs/Scan::Scan.def
* gm2-libs/Selective::Selective.def
* gm2-libs/StdIO::StdIO.def
* gm2-libs/Storage::Storage.def
* gm2-libs/StrCase::StrCase.def
* gm2-libs/StrIO::StrIO.def
* gm2-libs/StrLib::StrLib.def
* gm2-libs/StringConvert::StringConvert.def
* gm2-libs/SysExceptions::SysExceptions.def
* gm2-libs/SysStorage::SysStorage.def
* gm2-libs/TimeString::TimeString.def
* gm2-libs/UnixArgs::UnixArgs.def
* gm2-libs/cbuiltin::cbuiltin.def
* gm2-libs/cgetopt::cgetopt.def
* gm2-libs/cxxabi::cxxabi.def
* gm2-libs/dtoa::dtoa.def
* gm2-libs/errno::errno.def
* gm2-libs/gdbif::gdbif.def
* gm2-libs/ldtoa::ldtoa.def
* gm2-libs/libc::libc.def
* gm2-libs/libm::libm.def
* gm2-libs/sckt::sckt.def
* gm2-libs/termios::termios.def
* gm2-libs/wrapc::wrapc.def
@end menu

@node gm2-libs/ASCII, gm2-libs/Args, , Base libraries
@subsection gm2-libs/ASCII

@example
DEFINITION MODULE ASCII ;

EXPORT QUALIFIED
     nul, soh, stx, etx, eot, enq, ack, bel,
     bs , ht , nl , vt , np , cr , so , si ,
     dle, dc1, dc2, dc3, dc4, nak, syn, etb,
     can, em , sub, esc, fs , gs , rs , us ,
     sp ,  (* All the above are in order *)
     lf, ff, eof, del, tab, EOL ;

(*
   Note that lf, eof and EOL are added.
*)

CONST
@findex nul (const)
@findex soh (const)
@findex stx (const)
@findex etx (const)
     nul=000C; soh=001C; stx=002C; etx=003C;
@findex eot (const)
@findex enq (const)
@findex ack (const)
@findex bel (const)
     eot=004C; enq=005C; ack=006C; bel=007C;
@findex bs (const)
@findex ht (const)
@findex nl (const)
@findex vt (const)
     bs =010C; ht =011C; nl =012C; vt =013C;
@findex np (const)
@findex cr (const)
@findex so (const)
@findex si (const)
     np =014C; cr =015C; so =016C; si =017C;
@findex dle (const)
@findex dc1 (const)
@findex dc2 (const)
@findex dc3 (const)
     dle=020C; dc1=021C; dc2=022C; dc3=023C;
@findex dc4 (const)
@findex nak (const)
@findex syn (const)
@findex etb (const)
     dc4=024C; nak=025C; syn=026C; etb=027C;
@findex can (const)
@findex em (const)
@findex sub (const)
@findex esc (const)
     can=030C; em =031C; sub=032C; esc=033C;
@findex fs (const)
@findex gs (const)
@findex rs (const)
@findex us (const)
     fs =034C; gs =035C; rs =036C; us =037C;
@findex sp (const)
     sp =040C; (* All the above are in order *)
@findex lf (const)
@findex ff (const)
@findex eof (const)
@findex tab (const)
     lf =nl  ; ff =np  ; eof=eot ; tab=ht  ;
@findex del (const)
@findex EOL (const)
     del=177C; EOL=nl  ;

END ASCII.
@end example
@page

@node gm2-libs/Args, gm2-libs/Assertion, gm2-libs/ASCII, Base libraries
@subsection gm2-libs/Args

@example
DEFINITION MODULE Args ;

EXPORT QUALIFIED GetArg, Narg ;


(*
   GetArg - returns the nth argument from the command line.
            The success of the operation is returned.
*)

@findex GetArg
PROCEDURE GetArg (VAR a: ARRAY OF CHAR; n: CARDINAL) : BOOLEAN ;


(*
   Narg - returns the number of arguments available from
          command line.
*)

@findex Narg
PROCEDURE Narg () : CARDINAL ;


END Args.
@end example
@page

@node gm2-libs/Assertion, gm2-libs/Break, gm2-libs/Args, Base libraries
@subsection gm2-libs/Assertion

@example
DEFINITION MODULE Assertion ;

EXPORT QUALIFIED Assert ;


(*
   Assert - tests the boolean Condition, if it fails then HALT
            is called.
*)

@findex Assert
PROCEDURE Assert (Condition: BOOLEAN) ;


END Assertion.
@end example
@page

@node gm2-libs/Break, gm2-libs/Builtins, gm2-libs/Assertion, Base libraries
@subsection gm2-libs/Break

@example
DEFINITION MODULE Break ;

END Break.
@end example
@page

@node gm2-libs/Builtins, gm2-libs/COROUTINES, gm2-libs/Break, Base libraries
@subsection gm2-libs/Builtins

@example
DEFINITION MODULE Builtins ;

FROM SYSTEM IMPORT ADDRESS ;

(* floating point intrinsic procedure functions *)

@findex isfinitef
PROCEDURE __BUILTIN__ isfinitef (x: SHORTREAL) : BOOLEAN ;
@findex isfinite
PROCEDURE __BUILTIN__ isfinite (x: REAL) : BOOLEAN ;
@findex isfinitel
PROCEDURE __BUILTIN__ isfinitel (x: LONGREAL) : BOOLEAN ;

@findex sinf
PROCEDURE __BUILTIN__ sinf (x: SHORTREAL) : SHORTREAL ;
@findex sin
PROCEDURE __BUILTIN__ sin (x: REAL) : REAL ;
@findex sinl
PROCEDURE __BUILTIN__ sinl (x: LONGREAL) : LONGREAL ;

@findex cosf
PROCEDURE __BUILTIN__ cosf (x: SHORTREAL) : SHORTREAL ;
@findex cos
PROCEDURE __BUILTIN__ cos (x: REAL) : REAL ;
@findex cosl
PROCEDURE __BUILTIN__ cosl (x: LONGREAL) : LONGREAL ;

@findex sqrtf
PROCEDURE __BUILTIN__ sqrtf (x: SHORTREAL) : SHORTREAL ;
@findex sqrt
PROCEDURE __BUILTIN__ sqrt (x: REAL) : REAL ;
@findex sqrtl
PROCEDURE __BUILTIN__ sqrtl (x: LONGREAL) : LONGREAL ;

@findex atan2f
PROCEDURE __BUILTIN__ atan2f (x, y: SHORTREAL) : SHORTREAL ;
@findex atan2
PROCEDURE __BUILTIN__ atan2 (x, y: REAL) : REAL ;
@findex atan2l
PROCEDURE __BUILTIN__ atan2l (x, y: LONGREAL) : LONGREAL ;

@findex fabsf
PROCEDURE __BUILTIN__ fabsf (x: SHORTREAL) : SHORTREAL ;
@findex fabs
PROCEDURE __BUILTIN__ fabs (x: REAL) : REAL ;
@findex fabsl
PROCEDURE __BUILTIN__ fabsl (x: LONGREAL) : LONGREAL ;

@findex logf
PROCEDURE __BUILTIN__ logf (x: SHORTREAL) : SHORTREAL ;
@findex log
PROCEDURE __BUILTIN__ log (x: REAL) : REAL ;
@findex logl
PROCEDURE __BUILTIN__ logl (x: LONGREAL) : LONGREAL ;

@findex expf
PROCEDURE __BUILTIN__ expf (x: SHORTREAL) : SHORTREAL ;
@findex exp
PROCEDURE __BUILTIN__ exp (x: REAL) : REAL ;
@findex expl
PROCEDURE __BUILTIN__ expl (x: LONGREAL) : LONGREAL ;

@findex log10f
PROCEDURE __BUILTIN__ log10f (x: SHORTREAL) : SHORTREAL ;
@findex log10
PROCEDURE __BUILTIN__ log10 (x: REAL) : REAL ;
@findex log10l
PROCEDURE __BUILTIN__ log10l (x: LONGREAL) : LONGREAL ;

@findex exp10f
PROCEDURE __BUILTIN__ exp10f (x: SHORTREAL) : SHORTREAL ;
@findex exp10
PROCEDURE __BUILTIN__ exp10 (x: REAL) : REAL ;
@findex exp10l
PROCEDURE __BUILTIN__ exp10l (x: LONGREAL) : LONGREAL ;

@findex ilogbf
PROCEDURE __BUILTIN__ ilogbf (x: SHORTREAL) : INTEGER ;
@findex ilogb
PROCEDURE __BUILTIN__ ilogb (x: REAL) : INTEGER ;
@findex ilogbl
PROCEDURE __BUILTIN__ ilogbl (x: LONGREAL) : INTEGER ;

@findex huge_val
PROCEDURE __BUILTIN__ huge_val () : REAL ;
@findex huge_valf
PROCEDURE __BUILTIN__ huge_valf () : SHORTREAL ;
@findex huge_vall
PROCEDURE __BUILTIN__ huge_vall () : LONGREAL ;

@findex significand
PROCEDURE __BUILTIN__ significand (r: REAL) : REAL ;
@findex significandf
PROCEDURE __BUILTIN__ significandf (s: SHORTREAL) : SHORTREAL ;
@findex significandl
PROCEDURE __BUILTIN__ significandl (l: LONGREAL) : LONGREAL ;

@findex modf
PROCEDURE __BUILTIN__ modf (x: REAL; VAR y: REAL) : REAL ;
@findex modff
PROCEDURE __BUILTIN__ modff (x: SHORTREAL;
                             VAR y: SHORTREAL) : SHORTREAL ;
@findex modfl
PROCEDURE __BUILTIN__ modfl (x: LONGREAL; VAR y: LONGREAL) : LONGREAL ;

@findex signbit
PROCEDURE __BUILTIN__ signbit (r: REAL) : INTEGER ;
@findex signbitf
PROCEDURE __BUILTIN__ signbitf (s: SHORTREAL) : INTEGER ;
@findex signbitl
PROCEDURE __BUILTIN__ signbitl (l: LONGREAL) : INTEGER ;

@findex nextafter
PROCEDURE __BUILTIN__ nextafter (x, y: REAL) : REAL ;
@findex nextafterf
PROCEDURE __BUILTIN__ nextafterf (x, y: SHORTREAL) : SHORTREAL ;
@findex nextafterl
PROCEDURE __BUILTIN__ nextafterl (x, y: LONGREAL) : LONGREAL ;

@findex nexttoward
PROCEDURE __BUILTIN__ nexttoward (x, y: REAL) : LONGREAL ;
@findex nexttowardf
PROCEDURE __BUILTIN__ nexttowardf (x, y: SHORTREAL) : LONGREAL ;
@findex nexttowardl
PROCEDURE __BUILTIN__ nexttowardl (x, y: LONGREAL) : LONGREAL ;

@findex scalb
PROCEDURE __BUILTIN__ scalb (x, n: REAL) : REAL ;
@findex scalbf
PROCEDURE __BUILTIN__ scalbf (x, n: SHORTREAL) : SHORTREAL ;
@findex scalbl
PROCEDURE __BUILTIN__ scalbl (x, n: LONGREAL) : LONGREAL ;

@findex scalbln
PROCEDURE __BUILTIN__ scalbln (x: REAL; n: LONGINT) : REAL ;
@findex scalblnf
PROCEDURE __BUILTIN__ scalblnf (x: SHORTREAL; n: LONGINT) : SHORTREAL ;
@findex scalblnl
PROCEDURE __BUILTIN__ scalblnl (x: LONGREAL; n: LONGINT) : LONGREAL ;

@findex scalbn
PROCEDURE __BUILTIN__ scalbn (x: REAL; n: INTEGER) : REAL ;
@findex scalbnf
PROCEDURE __BUILTIN__ scalbnf (x: SHORTREAL; n: INTEGER) : SHORTREAL ;
@findex scalbnl
PROCEDURE __BUILTIN__ scalbnl (x: LONGREAL; n: INTEGER) : LONGREAL ;

(* complex arithmetic intrincic procedure functions *)

@findex cabsf
PROCEDURE __BUILTIN__ cabsf (z: SHORTCOMPLEX) : SHORTREAL ;
@findex cabs
PROCEDURE __BUILTIN__ cabs (z: COMPLEX) : REAL ;
@findex cabsl
PROCEDURE __BUILTIN__ cabsl (z: LONGCOMPLEX) : LONGREAL ;

@findex cargf
PROCEDURE __BUILTIN__ cargf (z: SHORTCOMPLEX) : SHORTREAL ;
@findex carg
PROCEDURE __BUILTIN__ carg (z: COMPLEX) : REAL ;
@findex cargl
PROCEDURE __BUILTIN__ cargl (z: LONGCOMPLEX) : LONGREAL ;

@findex conjf
PROCEDURE __BUILTIN__ conjf (z: SHORTCOMPLEX) : SHORTCOMPLEX ;
@findex conj
PROCEDURE __BUILTIN__ conj (z: COMPLEX) : COMPLEX ;
@findex conjl
PROCEDURE __BUILTIN__ conjl (z: LONGCOMPLEX) : LONGCOMPLEX ;

@findex cpowerf
PROCEDURE __BUILTIN__ cpowerf (base: SHORTCOMPLEX;
                               exp: SHORTREAL) : SHORTCOMPLEX ;
@findex cpower
PROCEDURE __BUILTIN__ cpower (base: COMPLEX; exp: REAL) : COMPLEX ;
@findex cpowerl
PROCEDURE __BUILTIN__ cpowerl (base: LONGCOMPLEX;
                               exp: LONGREAL) : LONGCOMPLEX ;

@findex csqrtf
PROCEDURE __BUILTIN__ csqrtf (z: SHORTCOMPLEX) : SHORTCOMPLEX ;
@findex csqrt
PROCEDURE __BUILTIN__ csqrt (z: COMPLEX) : COMPLEX ;
@findex csqrtl
PROCEDURE __BUILTIN__ csqrtl (z: LONGCOMPLEX) : LONGCOMPLEX ;

@findex cexpf
PROCEDURE __BUILTIN__ cexpf (z: SHORTCOMPLEX) : SHORTCOMPLEX ;
@findex cexp
PROCEDURE __BUILTIN__ cexp (z: COMPLEX) : COMPLEX ;
@findex cexpl
PROCEDURE __BUILTIN__ cexpl (z: LONGCOMPLEX) : LONGCOMPLEX ;

@findex clnf
PROCEDURE __BUILTIN__ clnf (z: SHORTCOMPLEX) : SHORTCOMPLEX ;
@findex cln
PROCEDURE __BUILTIN__ cln (z: COMPLEX) : COMPLEX ;
@findex clnl
PROCEDURE __BUILTIN__ clnl (z: LONGCOMPLEX) : LONGCOMPLEX ;

@findex csinf
PROCEDURE __BUILTIN__ csinf (z: SHORTCOMPLEX) : SHORTCOMPLEX ;
@findex csin
PROCEDURE __BUILTIN__ csin (z: COMPLEX) : COMPLEX ;
@findex csinl
PROCEDURE __BUILTIN__ csinl (z: LONGCOMPLEX) : LONGCOMPLEX ;

@findex ccosf
PROCEDURE __BUILTIN__ ccosf (z: SHORTCOMPLEX) : SHORTCOMPLEX ;
@findex ccos
PROCEDURE __BUILTIN__ ccos (z: COMPLEX) : COMPLEX ;
@findex ccosl
PROCEDURE __BUILTIN__ ccosl (z: LONGCOMPLEX) : LONGCOMPLEX ;

@findex ctanf
PROCEDURE __BUILTIN__ ctanf (z: SHORTCOMPLEX) : SHORTCOMPLEX ;
@findex ctan
PROCEDURE __BUILTIN__ ctan (z: COMPLEX) : COMPLEX ;
@findex ctanl
PROCEDURE __BUILTIN__ ctanl (z: LONGCOMPLEX) : LONGCOMPLEX ;

@findex carcsinf
PROCEDURE __BUILTIN__ carcsinf (z: SHORTCOMPLEX) : SHORTCOMPLEX ;
@findex carcsin
PROCEDURE __BUILTIN__ carcsin (z: COMPLEX) : COMPLEX ;
@findex carcsinl
PROCEDURE __BUILTIN__ carcsinl (z: LONGCOMPLEX) : LONGCOMPLEX ;

@findex carccosf
PROCEDURE __BUILTIN__ carccosf (z: SHORTCOMPLEX) : SHORTCOMPLEX ;
@findex carccos
PROCEDURE __BUILTIN__ carccos (z: COMPLEX) : COMPLEX ;
@findex carccosl
PROCEDURE __BUILTIN__ carccosl (z: LONGCOMPLEX) : LONGCOMPLEX ;

@findex carctanf
PROCEDURE __BUILTIN__ carctanf (z: SHORTCOMPLEX) : SHORTCOMPLEX ;
@findex carctan
PROCEDURE __BUILTIN__ carctan (z: COMPLEX) : COMPLEX ;
@findex carctanl
PROCEDURE __BUILTIN__ carctanl (z: LONGCOMPLEX) : LONGCOMPLEX ;

(* memory and string intrincic procedure functions *)

@findex alloca
PROCEDURE __BUILTIN__ alloca (i: CARDINAL) : ADDRESS ;
@findex memcpy
PROCEDURE __BUILTIN__ memcpy (dest, src: ADDRESS;
                              nbytes: CARDINAL) : ADDRESS ;
@findex index
PROCEDURE __BUILTIN__ index (s: ADDRESS; c: INTEGER) : ADDRESS ;
@findex rindex
PROCEDURE __BUILTIN__ rindex (s: ADDRESS; c: INTEGER) : ADDRESS ;
@findex memcmp
PROCEDURE __BUILTIN__ memcmp (s1, s2: ADDRESS;
                              nbytes: CARDINAL) : INTEGER ;
@findex memset
PROCEDURE __BUILTIN__ memset (s: ADDRESS; c: INTEGER;
                              nbytes: CARDINAL) : ADDRESS ;
@findex memmove
PROCEDURE __BUILTIN__ memmove (s1, s2: ADDRESS;
                               nbytes: CARDINAL) : ADDRESS ;
@findex strcat
PROCEDURE __BUILTIN__ strcat (dest, src: ADDRESS) : ADDRESS ;
@findex strncat
PROCEDURE __BUILTIN__ strncat (dest, src: ADDRESS;
                               nbytes: CARDINAL) : ADDRESS ;
@findex strcpy
PROCEDURE __BUILTIN__ strcpy (dest, src: ADDRESS) : ADDRESS ;
@findex strncpy
PROCEDURE __BUILTIN__ strncpy (dest, src: ADDRESS;
                               nbytes: CARDINAL) : ADDRESS ;
@findex strcmp
PROCEDURE __BUILTIN__ strcmp (s1, s2: ADDRESS) : INTEGER ;
@findex strncmp
PROCEDURE __BUILTIN__ strncmp (s1, s2: ADDRESS;
                               nbytes: CARDINAL) : INTEGER ;
@findex strlen
PROCEDURE __BUILTIN__ strlen (s: ADDRESS) : INTEGER ;
@findex strstr
PROCEDURE __BUILTIN__ strstr (haystack, needle: ADDRESS) : ADDRESS ;
@findex strpbrk
PROCEDURE __BUILTIN__ strpbrk (s, accept: ADDRESS) : ADDRESS ;
@findex strspn
PROCEDURE __BUILTIN__ strspn (s, accept: ADDRESS) : CARDINAL ;
@findex strcspn
PROCEDURE __BUILTIN__ strcspn (s, accept: ADDRESS) : CARDINAL ;
@findex strchr
PROCEDURE __BUILTIN__ strchr (s: ADDRESS; c: INTEGER) : ADDRESS ;
@findex strrchr
PROCEDURE __BUILTIN__ strrchr (s: ADDRESS; c: INTEGER) : ADDRESS ;

(*
   longjmp - this GCC builtin restricts the val to always 1.
*)
(* do not use these two builtins, as gcc, only really
   anticipates that the Ada front end should use them
   and it only uses them in its runtime exception handling.
   We leave them here in the hope that someday they will
   behave more like their libc counterparts.  *)

@findex longjmp
PROCEDURE __BUILTIN__ longjmp (env: ADDRESS; val: INTEGER) ;
@findex setjmp
PROCEDURE __BUILTIN__ setjmp (env: ADDRESS) : INTEGER ;


(*
   frame_address - returns the address of the frame.
                   The current frame is obtained if level is 0,
                   the next level up if level is 1 etc.
*)

@findex frame_address
PROCEDURE __BUILTIN__ frame_address (level: CARDINAL) : ADDRESS ;


(*
   return_address - returns the return address of function.
                    The current function return address is
                    obtained if level is 0,
                    the next level up if level is 1 etc.
*)

@findex return_address
PROCEDURE __BUILTIN__ return_address (level: CARDINAL) : ADDRESS ;


(*
   alloca_trace - this is a no-op which is used for internal debugging.
*)

@findex alloca_trace
PROCEDURE alloca_trace (returned: ADDRESS; nBytes: CARDINAL) : ADDRESS ;


END Builtins.
@end example
@page

@node gm2-libs/COROUTINES, gm2-libs/CmdArgs, gm2-libs/Builtins, Base libraries
@subsection gm2-libs/COROUTINES

@example
DEFINITION MODULE FOR "C" COROUTINES ;

CONST
   UnassignedPriority = 0 ;

TYPE
@findex INTERRUPTSOURCE (type)
   INTERRUPTSOURCE = CARDINAL ;
@findex PROTECTION (type)
   PROTECTION = [UnassignedPriority..7] ;

END COROUTINES.
@end example
@page

@node gm2-libs/CmdArgs, gm2-libs/Debug, gm2-libs/COROUTINES, Base libraries
@subsection gm2-libs/CmdArgs

@example
DEFINITION MODULE CmdArgs ;

EXPORT QUALIFIED GetArg, Narg ;


(*
   GetArg - returns the nth argument from the command line, CmdLine
            the success of the operation is returned.
*)

@findex GetArg
PROCEDURE GetArg (CmdLine: ARRAY OF CHAR;
                  n: CARDINAL; VAR Argi: ARRAY OF CHAR) : BOOLEAN ;


(*
   Narg - returns the number of arguments available from
          command line, CmdLine.
*)

@findex Narg
PROCEDURE Narg (CmdLine: ARRAY OF CHAR) : CARDINAL ;


END CmdArgs.
@end example
@page

@node gm2-libs/Debug, gm2-libs/DynamicStrings, gm2-libs/CmdArgs, Base libraries
@subsection gm2-libs/Debug

@example
DEFINITION MODULE Debug ;

(*
    Description: provides some simple debugging routines.
*)

EXPORT QUALIFIED Halt, DebugString ;


(*
   Halt - writes a message in the format:
          Module:Line:Message

          It then terminates by calling HALT.
*)

@findex Halt
PROCEDURE Halt (Message: ARRAY OF CHAR;
                LineNo: CARDINAL;
                Module: ARRAY OF CHAR) ;


(*
   DebugString - writes a string to the debugging device (Scn.Write).
                 It interprets \n as carriage return, linefeed.
*)

@findex DebugString
PROCEDURE DebugString (a: ARRAY OF CHAR) ;


END Debug.
@end example
@page

@node gm2-libs/DynamicStrings, gm2-libs/Environment, gm2-libs/Debug, Base libraries
@subsection gm2-libs/DynamicStrings

@example
DEFINITION MODULE DynamicStrings ;

FROM SYSTEM IMPORT ADDRESS ;
EXPORT QUALIFIED String,
                 InitString, KillString, Fin, InitStringCharStar,
                 InitStringChar, Index, RIndex,
                 Mark, Length, ConCat, ConCatChar, Assign, Dup, Add,
                 Equal, EqualCharStar, EqualArray, ToUpper, ToLower,
                 CopyOut, Mult, Slice,
                 RemoveWhitePrefix, RemoveWhitePostfix, RemoveComment,
                 char, string,
                 InitStringDB, InitStringCharStarDB, InitStringCharDB,
                 MultDB, DupDB, SliceDB,
                 PushAllocation, PopAllocation, PopAllocationExemption ;

TYPE
@findex String (type)
   String ;


(*
   InitString - creates and returns a String type object.
                Initial contents are, a.
*)

@findex InitString
PROCEDURE InitString (a: ARRAY OF CHAR) : String ;


(*
   KillString - frees String, s, and its contents.
                NIL is returned.
*)

@findex KillString
PROCEDURE KillString (s: String) : String ;


(*
   Fin - finishes with a string, it calls KillString with, s.
         The purpose of the procedure is to provide a short cut
         to calling KillString and then testing the return result.
*)

@findex Fin
PROCEDURE Fin (s: String) ;


(*
   InitStringCharStar - initializes and returns a String to contain
                        the C string.
*)

@findex InitStringCharStar
PROCEDURE InitStringCharStar (a: ADDRESS) : String ;


(*
   InitStringChar - initializes and returns a String to contain the
                    single character, ch.
*)

@findex InitStringChar
PROCEDURE InitStringChar (ch: CHAR) : String ;


(*
   Mark - marks String, s, ready for garbage collection.
*)

@findex Mark
PROCEDURE Mark (s: String) : String ;


(*
   Length - returns the length of the String, s.
*)

@findex Length
PROCEDURE Length (s: String) : CARDINAL ;


(*
   ConCat - returns String, a, after the contents of, b,
            have been appended.
*)

@findex ConCat
PROCEDURE ConCat (a, b: String) : String ;


(*
   ConCatChar - returns String, a, after character, ch,
                has been appended.
*)

@findex ConCatChar
PROCEDURE ConCatChar (a: String; ch: CHAR) : String ;


(*
   Assign - assigns the contents of, b, into, a.
            String, a, is returned.
*)

@findex Assign
PROCEDURE Assign (a, b: String) : String ;


(*
   Dup - duplicate a String, s, returning the copy of s.
*)

@findex Dup
PROCEDURE Dup (s: String) : String ;


(*
   Add - returns a new String which contains the contents of a and b.
*)

@findex Add
PROCEDURE Add (a, b: String) : String ;


(*
   Equal - returns TRUE if String, a, and, b, are equal.
*)

@findex Equal
PROCEDURE Equal (a, b: String) : BOOLEAN ;


(*
   EqualCharStar - returns TRUE if contents of String, s, is
                   the same as the string, a.
*)

@findex EqualCharStar
PROCEDURE EqualCharStar (s: String; a: ADDRESS) : BOOLEAN ;


(*
   EqualArray - returns TRUE if contents of String, s, is the
                same as the string, a.
*)

@findex EqualArray
PROCEDURE EqualArray (s: String; a: ARRAY OF CHAR) : BOOLEAN ;


(*
   Mult - returns a new string which is n concatenations of String, s.
          If n<=0 then an empty string is returned.
*)

@findex Mult
PROCEDURE Mult (s: String; n: CARDINAL) : String ;


(*
   Slice - returns a new string which contains the elements
           low..high-1

           strings start at element 0
           Slice(s, 0, 2)  will return elements 0, 1 but not 2
           Slice(s, 1, 3)  will return elements 1, 2 but not 3
           Slice(s, 2, 0)  will return elements 2..max
           Slice(s, 3, -1) will return elements 3..max-1
           Slice(s, 4, -2) will return elements 4..max-2
*)

@findex Slice
PROCEDURE Slice (s: String; low, high: INTEGER) : String ;


(*
   Index - returns the indice of the first occurance of, ch, in
           String, s. -1 is returned if, ch, does not exist.
           The search starts at position, o.
*)

@findex Index
PROCEDURE Index (s: String; ch: CHAR; o: CARDINAL) : INTEGER ;


(*
   RIndex - returns the indice of the last occurance of, ch,
            in String, s. The search starts at position, o.
            -1 is returned if, ch, is not found.
*)

@findex RIndex
PROCEDURE RIndex (s: String; ch: CHAR; o: CARDINAL) : INTEGER ;


(*
   RemoveComment - assuming that, comment, is a comment delimiter
                   which indicates anything to its right is a comment
                   then strip off the comment and also any white space
                   on the remaining right hand side.
                   It leaves any white space on the left hand side
                   alone.
*)

@findex RemoveComment
PROCEDURE RemoveComment (s: String; comment: CHAR) : String ;


(*
   RemoveWhitePrefix - removes any leading white space from String, s.
                       A new string is returned.
*)

@findex RemoveWhitePrefix
PROCEDURE RemoveWhitePrefix (s: String) : String ;


(*
   RemoveWhitePostfix - removes any leading white space from String, s.
                        A new string is returned.
*)

@findex RemoveWhitePostfix
PROCEDURE RemoveWhitePostfix (s: String) : String ;


(*
   ToUpper - returns string, s, after it has had its lower case
             characters replaced by upper case characters.
             The string, s, is not duplicated.
*)

@findex ToUpper
PROCEDURE ToUpper (s: String) : String ;


(*
   ToLower - returns string, s, after it has had its upper case
             characters replaced by lower case characters.
             The string, s, is not duplicated.
*)

@findex ToLower
PROCEDURE ToLower (s: String) : String ;


(*
   CopyOut - copies string, s, to a.
*)

@findex CopyOut
PROCEDURE CopyOut (VAR a: ARRAY OF CHAR; s: String) ;


(*
   char - returns the character, ch, at position, i, in String, s.
          As Slice the index can be negative so:

          char(s, 0) will return the first character
          char(s, 1) will return the second character
          char(s, -1) will return the last character
          char(s, -2) will return the penultimate character

          a nul character is returned if the index is out of range.
*)

@findex char
PROCEDURE char (s: String; i: INTEGER) : CHAR ;


(*
   string - returns the C style char * of String, s.
*)

@findex string
PROCEDURE string (s: String) : ADDRESS ;


(*
   to easily debug an application using this library one could use
   use the following macro processing defines:

   #define InitString(X) InitStringDB(X, __FILE__, __LINE__)
   #define InitStringCharStar(X) InitStringCharStarDB(X, \
     __FILE__, __LINE__)
   #define InitStringChar(X) InitStringCharDB(X, __FILE__, __LINE__)
   #define Mult(X,Y) MultDB(X, Y, __FILE__, __LINE__)
   #define Dup(X) DupDB(X, __FILE__, __LINE__)
   #define Slice(X,Y,Z) SliceDB(X, Y, Z, __FILE__, __LINE__)

   and then invoke gm2 with the -fcpp flag.
*)


(*
   InitStringDB - the debug version of InitString.
*)

@findex InitStringDB
PROCEDURE InitStringDB (a: ARRAY OF CHAR;
                        file: ARRAY OF CHAR; line: CARDINAL) : String ;


(*
   InitStringCharStarDB - the debug version of InitStringCharStar.
*)

@findex InitStringCharStarDB
PROCEDURE InitStringCharStarDB (a: ADDRESS;
                                file: ARRAY OF CHAR;
                                line: CARDINAL) : String ;


(*
   InitStringCharDB - the debug version of InitStringChar.
*)

@findex InitStringCharDB
PROCEDURE InitStringCharDB (ch: CHAR;
                            file: ARRAY OF CHAR;
                            line: CARDINAL) : String ;


(*
   MultDB - the debug version of MultDB.
*)

@findex MultDB
PROCEDURE MultDB (s: String; n: CARDINAL;
                  file: ARRAY OF CHAR; line: CARDINAL) : String ;


(*
   DupDB - the debug version of Dup.
*)

@findex DupDB
PROCEDURE DupDB (s: String;
                 file: ARRAY OF CHAR; line: CARDINAL) : String ;


(*
   SliceDB - debug version of Slice.
*)

@findex SliceDB
PROCEDURE SliceDB (s: String; low, high: INTEGER;
                   file: ARRAY OF CHAR; line: CARDINAL) : String ;

(*
   PushAllocation - pushes the current allocation/deallocation lists.
*)

@findex PushAllocation
PROCEDURE PushAllocation ;


(*
   PopAllocation - test to see that all strings are deallocated since
                   the last push.  Then it pops to the previous
                   allocation/deallocation lists.

                   If halt is true then the application terminates
                   with an exit code of 1.
*)

@findex PopAllocation
PROCEDURE PopAllocation (halt: BOOLEAN) ;


(*
   PopAllocationExemption - test to see that all strings are
                            deallocated, except string, e, since
                            the last push.
                            Then it pops to the previous
                            allocation/deallocation lists.

                            If halt is true then the application
                            terminates with an exit code of 1.

                            The string, e, is returned unmodified,
*)

@findex PopAllocationExemption
PROCEDURE PopAllocationExemption (halt: BOOLEAN; e: String) : String ;


END DynamicStrings.
@end example
@page

@node gm2-libs/Environment, gm2-libs/FIO, gm2-libs/DynamicStrings, Base libraries
@subsection gm2-libs/Environment

@example
DEFINITION MODULE Environment ;

EXPORT QUALIFIED GetEnvironment, PutEnvironment ;


(*
   GetEnvironment - gets the environment variable Env and places
      	       	    a copy of its value into string, dest.
                    It returns TRUE if the string Env was found in
                    the processes environment.
*)

@findex GetEnvironment
PROCEDURE GetEnvironment (Env: ARRAY OF CHAR;
                          VAR dest: ARRAY OF CHAR) : BOOLEAN ;


(*
   PutEnvironment - change or add an environment variable definition
                    EnvDef.
                    TRUE is returned if the environment variable was
                    set or changed successfully.
*)

@findex PutEnvironment
PROCEDURE PutEnvironment (EnvDef: ARRAY OF CHAR) : BOOLEAN ;


END Environment.
@end example
@page

@node gm2-libs/FIO, gm2-libs/FormatStrings, gm2-libs/Environment, Base libraries
@subsection gm2-libs/FIO

@example
DEFINITION MODULE FIO ;

(* Provides a simple buffered file input/output library.  *)


FROM SYSTEM IMPORT ADDRESS, BYTE ;

EXPORT QUALIFIED (* types *)
                 File,
                 (* procedures *)
                 OpenToRead, OpenToWrite, OpenForRandom, Close,
                 EOF, EOLN, WasEOLN, IsNoError, Exists, IsActive,
                 exists, openToRead, openToWrite, openForRandom,
                 SetPositionFromBeginning,
                 SetPositionFromEnd,
                 FindPosition,
                 ReadChar, ReadString,
                 WriteChar, WriteString, WriteLine,
                 WriteCardinal, ReadCardinal,
                 UnReadChar,
                 WriteNBytes, ReadNBytes,
                 FlushBuffer,
                 GetUnixFileDescriptor,
                 GetFileName, getFileName, getFileNameLength,
                 FlushOutErr,
                 (* variables *)
                 StdIn, StdOut, StdErr ;

TYPE
@findex File (type)
   File = CARDINAL ;

(* the following variables are initialized to their UNIX equivalents *)
VAR
@findex StdIn (var)
@findex StdOut (var)
@findex StdErr (var)
   StdIn, StdOut, StdErr: File ;



(*
   IsNoError - returns a TRUE if no error has occured on file, f.
*)

@findex IsNoError
PROCEDURE IsNoError (f: File) : BOOLEAN ;


(*
   IsActive - returns TRUE if the file, f, is still active.
*)

@findex IsActive
PROCEDURE IsActive (f: File) : BOOLEAN ;


(*
   Exists - returns TRUE if a file named, fname exists for reading.
*)

@findex Exists
PROCEDURE Exists (fname: ARRAY OF CHAR) : BOOLEAN ;


(*
   OpenToRead - attempts to open a file, fname, for reading and
                it returns this file.
                The success of this operation can be checked by
                calling IsNoError.
*)

@findex OpenToRead
PROCEDURE OpenToRead (fname: ARRAY OF CHAR) : File ;


(*
   OpenToWrite - attempts to open a file, fname, for write and
                 it returns this file.
                 The success of this operation can be checked by
                 calling IsNoError.
*)

@findex OpenToWrite
PROCEDURE OpenToWrite (fname: ARRAY OF CHAR) : File ;


(*
   OpenForRandom - attempts to open a file, fname, for random access
                   read or write and it returns this file.
                   The success of this operation can be checked by
                   calling IsNoError.
                   towrite, determines whether the file should be
                   opened for writing or reading.
                   newfile, determines whether a file should be
                   created if towrite is TRUE or whether the
                   previous file should be left alone,
                   allowing this descriptor to seek
                   and modify an existing file.
*)

@findex OpenForRandom
PROCEDURE OpenForRandom (fname: ARRAY OF CHAR;
                         towrite, newfile: BOOLEAN) : File ;


(*
   Close - close a file which has been previously opened using:
           OpenToRead, OpenToWrite, OpenForRandom.
           It is correct to close a file which has an error status.
*)

@findex Close
PROCEDURE Close (f: File) ;


(* the following functions are functionally equivalent to the above
   except they allow C style names.
*)

@findex exists
PROCEDURE exists        (fname: ADDRESS; flength: CARDINAL) : BOOLEAN ;
@findex openToRead
PROCEDURE openToRead    (fname: ADDRESS; flength: CARDINAL) : File ;
@findex openToWrite
PROCEDURE openToWrite   (fname: ADDRESS; flength: CARDINAL) : File ;
@findex openForRandom
PROCEDURE openForRandom (fname: ADDRESS; flength: CARDINAL;
                         towrite, newfile: BOOLEAN) : File ;


(*
   FlushBuffer - flush contents of the FIO file, f, to libc.
*)

@findex FlushBuffer
PROCEDURE FlushBuffer (f: File) ;


(*
   ReadNBytes - reads nBytes of a file into memory area, dest, returning
                the number of bytes actually read.
                This function will consume from the buffer and then
                perform direct libc reads. It is ideal for large reads.
*)

@findex ReadNBytes
PROCEDURE ReadNBytes (f: File; nBytes: CARDINAL;
                      dest: ADDRESS) : CARDINAL ;


(*
   ReadAny - reads HIGH(a) bytes into, a. All input
             is fully buffered, unlike ReadNBytes and thus is more
             suited to small reads.
*)

@findex ReadAny
PROCEDURE ReadAny (f: File; VAR a: ARRAY OF BYTE) ;


(*
   WriteNBytes - writes nBytes from memory area src to a file
                 returning the number of bytes actually written.
                 This function will flush the buffer and then
                 write the nBytes using a direct write from libc.
                 It is ideal for large writes.
*)

@findex WriteNBytes
PROCEDURE WriteNBytes (f: File; nBytes: CARDINAL;
                       src: ADDRESS) : CARDINAL ;


(*
   WriteAny - writes HIGH(a) bytes onto, file, f. All output
              is fully buffered, unlike WriteNBytes and thus is more
              suited to small writes.
*)

@findex WriteAny
PROCEDURE WriteAny (f: File; VAR a: ARRAY OF BYTE) ;


(*
   WriteChar - writes a single character to file, f.
*)

@findex WriteChar
PROCEDURE WriteChar (f: File; ch: CHAR) ;


(*
   EOF - tests to see whether a file, f, has reached end of file.
*)

@findex EOF
PROCEDURE EOF (f: File) : BOOLEAN ;


(*
   EOLN - tests to see whether a file, f, is about to read a newline.
          It does NOT consume the newline.  It reads the next character
          and then immediately unreads the character.
*)

@findex EOLN
PROCEDURE EOLN (f: File) : BOOLEAN ;


(*
   WasEOLN - tests to see whether a file, f, has just read a newline
             character.
*)

@findex WasEOLN
PROCEDURE WasEOLN (f: File) : BOOLEAN ;


(*
   ReadChar - returns a character read from file, f.
              Sensible to check with IsNoError or EOF after calling
              this function.
*)

@findex ReadChar
PROCEDURE ReadChar (f: File) : CHAR ;


(*
   UnReadChar - replaces a character, ch, back into file, f.
                This character must have been read by ReadChar
                and it does not allow successive calls.  It may
                only be called if the previous read was successful,
                end of file or end of line seen.
*)

@findex UnReadChar
PROCEDURE UnReadChar (f: File ; ch: CHAR) ;


(*
   WriteLine - writes out a linefeed to file, f.
*)

@findex WriteLine
PROCEDURE WriteLine (f: File) ;


(*
   WriteString - writes a string to file, f.
*)

@findex WriteString
PROCEDURE WriteString (f: File; a: ARRAY OF CHAR) ;


(*
   ReadString - reads a string from file, f, into string, a.
                It terminates the string if HIGH is reached or
                if a newline is seen or an error occurs.
*)

@findex ReadString
PROCEDURE ReadString (f: File; VAR a: ARRAY OF CHAR) ;


(*
   WriteCardinal - writes a CARDINAL to file, f.
                   It writes the binary image of the CARDINAL.
                   to file, f.
*)

@findex WriteCardinal
PROCEDURE WriteCardinal (f: File; c: CARDINAL) ;


(*
   ReadCardinal - reads a CARDINAL from file, f.
                  It reads a bit image of a CARDINAL
                  from file, f.
*)

@findex ReadCardinal
PROCEDURE ReadCardinal (f: File) : CARDINAL ;


(*
   GetUnixFileDescriptor - returns the UNIX file descriptor of a file.
                           Useful when combining FIO.mod with select
                           (in Selective.def - but note the comments in
                            Selective about using read/write primatives)
*)

@findex GetUnixFileDescriptor
PROCEDURE GetUnixFileDescriptor (f: File) : INTEGER ;


(*
   SetPositionFromBeginning - sets the position from the beginning
                              of the file.
*)

@findex SetPositionFromBeginning
PROCEDURE SetPositionFromBeginning (f: File; pos: LONGINT) ;


(*
   SetPositionFromEnd - sets the position from the end of the file.
*)

@findex SetPositionFromEnd
PROCEDURE SetPositionFromEnd (f: File; pos: LONGINT) ;


(*
   FindPosition - returns the current absolute position in file, f.
*)

@findex FindPosition
PROCEDURE FindPosition (f: File) : LONGINT ;


(*
   GetFileName - assigns, a, with the filename associated with, f.
*)

@findex GetFileName
PROCEDURE GetFileName (f: File; VAR a: ARRAY OF CHAR) ;


(*
   getFileName - returns the address of the filename associated with, f.
*)

@findex getFileName
PROCEDURE getFileName (f: File) : ADDRESS ;


(*
   getFileNameLength - returns the number of characters associated with
                       filename, f.
*)

@findex getFileNameLength
PROCEDURE getFileNameLength (f: File) : CARDINAL ;


(*
   FlushOutErr - flushes, StdOut, and, StdErr.
*)

@findex FlushOutErr
PROCEDURE FlushOutErr ;


END FIO.
@end example
@page

@node gm2-libs/FormatStrings, gm2-libs/FpuIO, gm2-libs/FIO, Base libraries
@subsection gm2-libs/FormatStrings

@example
DEFINITION MODULE FormatStrings ;

FROM SYSTEM IMPORT BYTE ;
FROM DynamicStrings IMPORT String ;
EXPORT QUALIFIED Sprintf0, Sprintf1, Sprintf2, Sprintf3, Sprintf4,
                 HandleEscape ;


(*
   Sprintf0 - returns a String containing, fmt, after it has had its
              escape sequences translated.
*)

@findex Sprintf0
PROCEDURE Sprintf0 (fmt: String) : String ;


(*
   Sprintf1 - returns a String containing, fmt, together with
              encapsulated entity, w. It only formats the
              first %s or %d with n.
*)

@findex Sprintf1
PROCEDURE Sprintf1 (fmt: String; w: ARRAY OF BYTE) : String ;


(*
   Sprintf2 - returns a string, fmt, which has been formatted.
*)

@findex Sprintf2
PROCEDURE Sprintf2 (fmt: String; w1, w2: ARRAY OF BYTE) : String ;


(*
   Sprintf3 - returns a string, fmt, which has been formatted.
*)

@findex Sprintf3
PROCEDURE Sprintf3 (fmt: String; w1, w2, w3: ARRAY OF BYTE) : String ;


(*
   Sprintf4 - returns a string, fmt, which has been formatted.
*)

@findex Sprintf4
PROCEDURE Sprintf4 (fmt: String;
                    w1, w2, w3, w4: ARRAY OF BYTE) : String ;


(*
   HandleEscape - translates \a, \b, \e, \f, \n, \r, \x[hex] \[octal]
                  into their respective ascii codes.  It also converts
                  \[any] into a single [any] character.
*)

@findex HandleEscape
PROCEDURE HandleEscape (s: String) : String ;


END FormatStrings.
@end example
@page

@node gm2-libs/FpuIO, gm2-libs/GetOpt, gm2-libs/FormatStrings, Base libraries
@subsection gm2-libs/FpuIO

@example
DEFINITION MODULE FpuIO ;

EXPORT QUALIFIED ReadReal, WriteReal, StrToReal, RealToStr,
                 ReadLongReal, WriteLongReal, StrToLongReal,
                 LongRealToStr,
                 ReadLongInt, WriteLongInt, StrToLongInt,
                 LongIntToStr ;


@findex ReadReal
PROCEDURE ReadReal (VAR x: REAL) ;
@findex WriteReal
PROCEDURE WriteReal (x: REAL; TotalWidth, FractionWidth: CARDINAL) ;
@findex StrToReal
PROCEDURE StrToReal (a: ARRAY OF CHAR ; VAR x: REAL) ;
@findex RealToStr
PROCEDURE RealToStr (x: REAL; TotalWidth, FractionWidth: CARDINAL;
                     VAR a: ARRAY OF CHAR) ;

@findex ReadLongReal
PROCEDURE ReadLongReal (VAR x: LONGREAL) ;
@findex WriteLongReal
PROCEDURE WriteLongReal (x: LONGREAL;
                         TotalWidth, FractionWidth: CARDINAL) ;
@findex StrToLongReal
PROCEDURE StrToLongReal (a: ARRAY OF CHAR ; VAR x: LONGREAL) ;
@findex LongRealToStr
PROCEDURE LongRealToStr (x: LONGREAL;
                         TotalWidth, FractionWidth: CARDINAL;
                         VAR a: ARRAY OF CHAR) ;

@findex ReadLongInt
PROCEDURE ReadLongInt (VAR x: LONGINT) ;
@findex WriteLongInt
PROCEDURE WriteLongInt (x: LONGINT; n: CARDINAL) ;
@findex StrToLongInt
PROCEDURE StrToLongInt (a: ARRAY OF CHAR ; VAR x: LONGINT) ;
@findex LongIntToStr
PROCEDURE LongIntToStr (x: LONGINT; n: CARDINAL; VAR a: ARRAY OF CHAR) ;


END FpuIO.
@end example
@page

@node gm2-libs/GetOpt, gm2-libs/IO, gm2-libs/FpuIO, Base libraries
@subsection gm2-libs/GetOpt

@example
DEFINITION MODULE GetOpt ;

FROM SYSTEM IMPORT ADDRESS ;
FROM DynamicStrings IMPORT String ;

CONST
@findex no_argument (const)
   no_argument = 0 ;
@findex required_argument (const)
   required_argument = 1 ;
@findex optional_argument (const)
   optional_argument = 2 ;

TYPE
@findex LongOptions (type)
   LongOptions ;
@findex PtrToInteger (type)
   PtrToInteger = POINTER TO INTEGER ;

(*
   GetOpt - call C getopt and fill in the parameters:
            optarg, optind, opterr and optop.
*)

@findex GetOpt
PROCEDURE GetOpt (argc: INTEGER; argv: ADDRESS; optstring: String;
                  VAR optarg: String;
                  VAR optind, opterr, optopt: INTEGER) : CHAR ;


(*
   InitLongOptions - creates and returns a LongOptions empty array.
*)

@findex InitLongOptions
PROCEDURE InitLongOptions () : LongOptions ;


(*
   AddLongOption - appends long option @{name, has_arg, flag, val@} to the
                   array of options and new long options array is
                   returned.
                   The old array, lo, should no longer be used.

   (from man 3 getopt)
       The meanings of the different fields are:

       name   is the name of the long option.

       has_arg
              is: no_argument (or 0) if the option does not take an
              argument; required_argument (or  1) if the option
              requires an argument; or optional_argument (or 2) if
              the option takes an optional argument.

       flag   specifies how results are returned for a long option.
              If flag is NULL, then getopt_long() returns val.
              (For example, the calling program may set val to the
              equivalent short option character).  Otherwise,
              getopt_long() returns 0, and flag points to a
              variable which is set to val if the option is found,
              but left unchanged if the option is not found.

       val    is the value to return, or to load into the variable
              pointed to by flag.

       The last element of the array has to be filled with zeros.
*)

@findex AddLongOption
PROCEDURE AddLongOption (lo: LongOptions;
                         name: String; has_arg: INTEGER;
                         flag: PtrToInteger;
                         val: INTEGER) : LongOptions ;


(*
   KillLongOptions - returns NIL and also frees up memory
                     associated with, lo.
*)

@findex KillLongOptions
PROCEDURE KillLongOptions (lo: LongOptions) : LongOptions ;


(*
   GetOptLong - works like GetOpt but will accept long options (using
                two dashes).  If the program only accepts long options
                then optstring should be an empty string, not NIL.
*)

@findex GetOptLong
PROCEDURE GetOptLong (argc: INTEGER; argv: ADDRESS; optstring: String;
                      longopts: LongOptions;
                      VAR longindex: INTEGER) : INTEGER ;


(*
   GetOptLongOnly - works like GetOptLong except that a single dash
                    can be used for a long option.
*)

@findex GetOptLongOnly
PROCEDURE GetOptLongOnly (argc: INTEGER; argv: ADDRESS;
                          optstring: String; longopts: LongOptions;
                          VAR longindex: INTEGER) : INTEGER ;


END GetOpt.
@end example
@page

@node gm2-libs/IO, gm2-libs/Indexing, gm2-libs/GetOpt, Base libraries
@subsection gm2-libs/IO

@example
DEFINITION MODULE IO ;

(*
   Description: provides Read, Write, Errors procedures that map onto UNIX
                file descriptors 0, 1 and 2. This is achieved by using
                FIO if we are in buffered mode and using libc.write
                if not.
*)

EXPORT QUALIFIED Read, Write, Error,
                 UnBufferedMode, BufferedMode,
                 EchoOn, EchoOff ;


@findex Read
PROCEDURE Read (VAR ch: CHAR) ;
@findex Write
PROCEDURE Write (ch: CHAR) ;
@findex Error
PROCEDURE Error (ch: CHAR) ;


(*
   UnBufferedMode - places file descriptor, fd, into an unbuffered mode.
*)

@findex UnBufferedMode
PROCEDURE UnBufferedMode (fd: INTEGER; input: BOOLEAN) ;


(*
   BufferedMode - places file descriptor, fd, into a buffered mode.
*)

@findex BufferedMode
PROCEDURE BufferedMode (fd: INTEGER; input: BOOLEAN) ;


(*
   EchoOn - turns on echoing for file descriptor, fd.  This
            only really makes sence for a file descriptor opened
            for terminal input or maybe some specific file descriptor
            which is attached to a particular piece of hardware.
*)

@findex EchoOn
PROCEDURE EchoOn (fd: INTEGER; input: BOOLEAN) ;


(*
   EchoOff - turns off echoing for file descriptor, fd.  This
             only really makes sence for a file descriptor opened
             for terminal input or maybe some specific file descriptor
             which is attached to a particular piece of hardware.
*)

@findex EchoOff
PROCEDURE EchoOff (fd: INTEGER; input: BOOLEAN) ;


END IO.
@end example
@page

@node gm2-libs/Indexing, gm2-libs/LMathLib0, gm2-libs/IO, Base libraries
@subsection gm2-libs/Indexing

@example
DEFINITION MODULE Indexing ;

FROM SYSTEM IMPORT ADDRESS ;
EXPORT QUALIFIED Index, InitIndex, KillIndex, GetIndice, PutIndice,
                 HighIndice, LowIndice, InBounds, IsIndiceInIndex,
                 RemoveIndiceFromIndex, IncludeIndiceIntoIndex,
                 ForeachIndiceInIndexDo, DeleteIndice, DebugIndex ;

TYPE
@findex Index (type)
   Index ;
@findex IndexProcedure (type)
   IndexProcedure = PROCEDURE (ADDRESS) ;


(*
   InitIndex - creates and returns an Index.
*)

@findex InitIndex
PROCEDURE InitIndex (low: CARDINAL) : Index ;


(*
   KillIndex - returns Index to free storage.
*)

@findex KillIndex
PROCEDURE KillIndex (i: Index) : Index ;


(*
   DebugIndex - turns on debugging within an index.
*)

@findex DebugIndex
PROCEDURE DebugIndex (i: Index) : Index ;


(*
   InBounds - returns TRUE if indice, n, is within the bounds
              of the dynamic array.
*)

@findex InBounds
PROCEDURE InBounds (i: Index; n: CARDINAL) : BOOLEAN ;


(*
   HighIndice - returns the last legally accessible indice of this array.
*)

@findex HighIndice
PROCEDURE HighIndice (i: Index) : CARDINAL ;


(*
   LowIndice - returns the first legally accessible indice of this array.
*)

@findex LowIndice
PROCEDURE LowIndice (i: Index) : CARDINAL ;


(*
   PutIndice - places, a, into the dynamic array at position i[n]
*)

@findex PutIndice
PROCEDURE PutIndice (i: Index; n: CARDINAL; a: ADDRESS) ;


(*
   GetIndice - retrieves, element i[n] from the dynamic array.
*)

@findex GetIndice
PROCEDURE GetIndice (i: Index; n: CARDINAL) : ADDRESS ;


(*
   IsIndiceInIndex - returns TRUE if, a, is in the index, i.
*)

@findex IsIndiceInIndex
PROCEDURE IsIndiceInIndex (i: Index; a: ADDRESS) : BOOLEAN ;


(*
   RemoveIndiceFromIndex - removes, a, from Index, i.
*)

@findex RemoveIndiceFromIndex
PROCEDURE RemoveIndiceFromIndex (i: Index; a: ADDRESS) ;


(*
   DeleteIndice - delete i[j] from the array.
*)

@findex DeleteIndice
PROCEDURE DeleteIndice (i: Index; j: CARDINAL) ;


(*
   IncludeIndiceIntoIndex - if the indice is not in the index, then
                            add it at the end.
*)

@findex IncludeIndiceIntoIndex
PROCEDURE IncludeIndiceIntoIndex (i: Index; a: ADDRESS) ;


(*
   ForeachIndiceInIndexDo - for each j indice of i, call procedure p(i[j])
*)

@findex ForeachIndiceInIndexDo
PROCEDURE ForeachIndiceInIndexDo (i: Index; p: IndexProcedure) ;


END Indexing.
@end example
@page

@node gm2-libs/LMathLib0, gm2-libs/LegacyReal, gm2-libs/Indexing, Base libraries
@subsection gm2-libs/LMathLib0

@example
DEFINITION MODULE LMathLib0 ;

CONST
   pi   = 3.1415926535897932384626433832795028841972;
   exp1 = 2.7182818284590452353602874713526624977572;


@findex sqrt
PROCEDURE __BUILTIN__ sqrt (x: LONGREAL) : LONGREAL ;
@findex exp
PROCEDURE exp (x: LONGREAL) : LONGREAL ;
@findex ln
PROCEDURE ln (x: LONGREAL) : LONGREAL ;
@findex sin
PROCEDURE __BUILTIN__ sin (x: LONGREAL) : LONGREAL ;
@findex cos
PROCEDURE __BUILTIN__ cos (x: LONGREAL) : LONGREAL ;
@findex tan
PROCEDURE tan (x: LONGREAL) : LONGREAL ;
@findex arctan
PROCEDURE arctan (x: LONGREAL) : LONGREAL ;
@findex entier
PROCEDURE entier (x: LONGREAL) : INTEGER ;


END LMathLib0.
@end example
@page

@node gm2-libs/LegacyReal, gm2-libs/M2Dependent, gm2-libs/LMathLib0, Base libraries
@subsection gm2-libs/LegacyReal

@example
DEFINITION MODULE LegacyReal ;

TYPE
   REAL = SHORTREAL ;


END LegacyReal.
@end example
@page

@node gm2-libs/M2Dependent, gm2-libs/M2EXCEPTION, gm2-libs/LegacyReal, Base libraries
@subsection gm2-libs/M2Dependent

@example
DEFINITION MODULE M2Dependent ;

FROM SYSTEM IMPORT ADDRESS ;


TYPE
@findex ArgCVEnvP (type)
   ArgCVEnvP = PROCEDURE (INTEGER, ADDRESS, ADDRESS) ;


@findex ConstructModules
PROCEDURE ConstructModules (applicationmodule: ADDRESS;
                            argc: INTEGER; argv, envp: ADDRESS) ;

@findex DeconstructModules
PROCEDURE DeconstructModules (applicationmodule: ADDRESS;
                              argc: INTEGER; argv, envp: ADDRESS) ;


(*
   RegisterModule - adds module name to the list of outstanding
                    modules which need to have their dependencies
                    explored to determine initialization order.
*)

@findex RegisterModule
PROCEDURE RegisterModule (name: ADDRESS;
                          init, fini:  ArgCVEnvP;
                          dependencies: PROC) ;


(*
   RequestDependant - used to specify that modulename is dependant upon
                      module dependantmodule.
*)

@findex RequestDependant
PROCEDURE RequestDependant (modulename, dependantmodule: ADDRESS) ;


END M2Dependent.
@end example
@page

@node gm2-libs/M2EXCEPTION, gm2-libs/M2LINK, gm2-libs/M2Dependent, Base libraries
@subsection gm2-libs/M2EXCEPTION

@example
DEFINITION MODULE M2EXCEPTION;


(* This enumerated list of exceptions must match the exceptions in gm2-libs-iso to
   allow mixed module dialect projects.  *)

TYPE
@findex M2Exceptions (type)
  M2Exceptions =
    (indexException,     rangeException,         caseSelectException,  invalidLocation,
     functionException,  wholeValueException,    wholeDivException,    realValueException,
     realDivException,   complexValueException,  complexDivException,  protException,
     sysException,       coException,            exException
    );


(* If the program or coroutine is in the exception state then return the enumeration
   value representing the exception cause.  If it is not in the exception state then
   raises and exception (exException).  *)

@findex M2Exception
PROCEDURE M2Exception () : M2Exceptions;

(* Returns TRUE if the program or coroutine is in the exception state.
   Returns FALSE if the program or coroutine is not in the exception state.  *)

@findex IsM2Exception
PROCEDURE IsM2Exception () : BOOLEAN;


END M2EXCEPTION.
@end example
@page

@node gm2-libs/M2LINK, gm2-libs/M2RTS, gm2-libs/M2EXCEPTION, Base libraries
@subsection gm2-libs/M2LINK

@example
DEFINITION MODULE FOR "C" M2LINK ;


TYPE
@findex PtrToChar (type)
   PtrToChar = POINTER TO CHAR ;

(* These variables are set by the compiler in the program module
   according to linking command line options.  *)

VAR
@findex ForcedModuleInitOrder (var)
   ForcedModuleInitOrder: PtrToChar ;
@findex StaticInitialization (var)
   StaticInitialization : BOOLEAN ;


@findex END M2LINK. (var)
END M2LINK.
@end example
@page

@node gm2-libs/M2RTS, gm2-libs/MathLib0, gm2-libs/M2LINK, Base libraries
@subsection gm2-libs/M2RTS

@example
DEFINITION MODULE M2RTS ;

FROM SYSTEM IMPORT ADDRESS ;


TYPE
@findex ArgCVEnvP (type)
   ArgCVEnvP = PROCEDURE (INTEGER, ADDRESS, ADDRESS) ;


@findex ConstructModules
PROCEDURE ConstructModules (applicationmodule: ADDRESS;
                            argc: INTEGER; argv, envp: ADDRESS) ;

@findex DeconstructModules
PROCEDURE DeconstructModules (applicationmodule: ADDRESS;
                              argc: INTEGER; argv, envp: ADDRESS) ;


(*
   RegisterModule - adds module name to the list of outstanding
                    modules which need to have their dependencies
                    explored to determine initialization order.
*)

@findex RegisterModule
PROCEDURE RegisterModule (name: ADDRESS;
                          init, fini:  ArgCVEnvP;
                          dependencies: PROC) ;


(*
   RequestDependant - used to specify that modulename is dependant upon
                      module dependantmodule.
*)

@findex RequestDependant
PROCEDURE RequestDependant (modulename, dependantmodule: ADDRESS) ;


(*
   InstallTerminationProcedure - installs a procedure, p, which will
                                 be called when the procedure
                                 ExecuteTerminationProcedures
                                 is invoked.  It returns TRUE is the
                                 procedure is installed.
*)

@findex InstallTerminationProcedure
PROCEDURE InstallTerminationProcedure (p: PROC) : BOOLEAN ;


(*
   ExecuteInitialProcedures - executes the initial procedures installed
                              by InstallInitialProcedure.
*)

@findex ExecuteInitialProcedures
PROCEDURE ExecuteInitialProcedures ;


(*
   InstallInitialProcedure - installs a procedure to be executed just
                             before the BEGIN code section of the main
                             program module.
*)

@findex InstallInitialProcedure
PROCEDURE InstallInitialProcedure (p: PROC) : BOOLEAN ;


(*
   ExecuteTerminationProcedures - calls each installed termination procedure
                                  in reverse order.
*)

@findex ExecuteTerminationProcedures
PROCEDURE ExecuteTerminationProcedures ;


(*
   Terminate - provides compatibility for pim.  It call exit with
               the exitcode provided in a prior call to ExitOnHalt
               (or zero if ExitOnHalt was never called).  It does
               not call ExecuteTerminationProcedures.
*)

@findex Terminate
PROCEDURE Terminate <* noreturn *> ;


(*
   HALT - terminate the current program.  The procedure Terminate
          is called before the program is stopped.  The parameter
          exitcode is optional.  If the parameter is not supplied
          HALT will call libc 'abort', otherwise it will exit with
          the code supplied.  Supplying a parameter to HALT has the
          same effect as calling ExitOnHalt with the same code and
          then calling HALT with no parameter.
*)

@findex HALT
PROCEDURE HALT ([exitcode: INTEGER = -1]) <* noreturn *> ;


(*
   Halt - provides a more user friendly version of HALT, which takes
          four parameters to aid debugging.
*)

@findex Halt
PROCEDURE Halt (file: ARRAY OF CHAR; line: CARDINAL;
                function: ARRAY OF CHAR; description: ARRAY OF CHAR)
		<* noreturn *> ;


(*
   ExitOnHalt - if HALT is executed then call exit with the exit code, e.
*)

@findex ExitOnHalt
PROCEDURE ExitOnHalt (e: INTEGER) ;


(*
   ErrorMessage - emits an error message to stderr and then calls exit (1).
*)

@findex ErrorMessage
PROCEDURE ErrorMessage (message: ARRAY OF CHAR;
                        file: ARRAY OF CHAR;
                        line: CARDINAL;
                        function: ARRAY OF CHAR) <* noreturn *> ;


(*
   Length - returns the length of a string, a. This is called whenever
            the user calls LENGTH and the parameter cannot be calculated
            at compile time.
*)

@findex Length
PROCEDURE Length (a: ARRAY OF CHAR) : CARDINAL ;


(*
   The following are the runtime exception handler routines.
*)

@findex AssignmentException
PROCEDURE AssignmentException (filename: ADDRESS; line, column: CARDINAL; scope, message: ADDRESS) ;
@findex ReturnException
PROCEDURE ReturnException (filename: ADDRESS; line, column: CARDINAL; scope, message: ADDRESS) ;
@findex IncException
PROCEDURE IncException (filename: ADDRESS; line, column: CARDINAL; scope, message: ADDRESS) ;
@findex DecException
PROCEDURE DecException (filename: ADDRESS; line, column: CARDINAL; scope, message: ADDRESS) ;
@findex InclException
PROCEDURE InclException (filename: ADDRESS; line, column: CARDINAL; scope, message: ADDRESS) ;
@findex ExclException
PROCEDURE ExclException (filename: ADDRESS; line, column: CARDINAL; scope, message: ADDRESS) ;
@findex ShiftException
PROCEDURE ShiftException (filename: ADDRESS; line, column: CARDINAL; scope, message: ADDRESS) ;
@findex RotateException
PROCEDURE RotateException (filename: ADDRESS; line, column: CARDINAL; scope, message: ADDRESS) ;
@findex StaticArraySubscriptException
PROCEDURE StaticArraySubscriptException (filename: ADDRESS; line, column: CARDINAL; scope, message: ADDRESS) ;
@findex DynamicArraySubscriptException
PROCEDURE DynamicArraySubscriptException (filename: ADDRESS; line, column: CARDINAL; scope, message: ADDRESS) ;
@findex ForLoopBeginException
PROCEDURE ForLoopBeginException (filename: ADDRESS; line, column: CARDINAL; scope, message: ADDRESS) ;
@findex ForLoopToException
PROCEDURE ForLoopToException (filename: ADDRESS; line, column: CARDINAL; scope, message: ADDRESS) ;
@findex ForLoopEndException
PROCEDURE ForLoopEndException (filename: ADDRESS; line, column: CARDINAL; scope, message: ADDRESS) ;
@findex PointerNilException
PROCEDURE PointerNilException (filename: ADDRESS; line, column: CARDINAL; scope, message: ADDRESS) ;
@findex NoReturnException
PROCEDURE NoReturnException (filename: ADDRESS; line, column: CARDINAL; scope, message: ADDRESS) ;
@findex CaseException
PROCEDURE CaseException (filename: ADDRESS; line, column: CARDINAL; scope, message: ADDRESS) ;
@findex WholeNonPosDivException
PROCEDURE WholeNonPosDivException (filename: ADDRESS; line, column: CARDINAL; scope, message: ADDRESS) ;
@findex WholeNonPosModException
PROCEDURE WholeNonPosModException (filename: ADDRESS; line, column: CARDINAL; scope, message: ADDRESS) ;
@findex WholeZeroDivException
PROCEDURE WholeZeroDivException (filename: ADDRESS; line, column: CARDINAL; scope, message: ADDRESS) ;
@findex WholeZeroRemException
PROCEDURE WholeZeroRemException (filename: ADDRESS; line, column: CARDINAL; scope, message: ADDRESS) ;
@findex WholeValueException
PROCEDURE WholeValueException (filename: ADDRESS; line, column: CARDINAL; scope, message: ADDRESS) ;
@findex RealValueException
PROCEDURE RealValueException (filename: ADDRESS; line, column: CARDINAL; scope, message: ADDRESS) ;
@findex ParameterException
PROCEDURE ParameterException (filename: ADDRESS; line, column: CARDINAL; scope, message: ADDRESS) ;
@findex NoException
PROCEDURE NoException (filename: ADDRESS; line, column: CARDINAL; scope, message: ADDRESS) ;


END M2RTS.
@end example
@page

@node gm2-libs/MathLib0, gm2-libs/MemUtils, gm2-libs/M2RTS, Base libraries
@subsection gm2-libs/MathLib0

@example
DEFINITION MODULE MathLib0 ;

CONST
   pi   = 3.1415926535897932384626433832795028841972;
   exp1 = 2.7182818284590452353602874713526624977572;


@findex sqrt
PROCEDURE __BUILTIN__ sqrt (x: REAL) : REAL ;
@findex exp
PROCEDURE exp (x: REAL) : REAL ;
@findex ln
PROCEDURE ln (x: REAL) : REAL ;
@findex sin
PROCEDURE __BUILTIN__ sin (x: REAL) : REAL ;
@findex cos
PROCEDURE __BUILTIN__ cos (x: REAL) : REAL ;
@findex tan
PROCEDURE tan (x: REAL) : REAL ;
@findex arctan
PROCEDURE arctan (x: REAL) : REAL ;
@findex entier
PROCEDURE entier (x: REAL) : INTEGER ;


END MathLib0.
@end example
@page

@node gm2-libs/MemUtils, gm2-libs/NumberIO, gm2-libs/MathLib0, Base libraries
@subsection gm2-libs/MemUtils

@example
DEFINITION MODULE MemUtils ;

FROM SYSTEM IMPORT ADDRESS ;
EXPORT QUALIFIED MemCopy, MemZero ;


(*
   MemCopy - copys a region of memory to the required destination.
*)

@findex MemCopy
PROCEDURE MemCopy (from: ADDRESS; length: CARDINAL; to: ADDRESS) ;


(*
   MemZero - sets a region of memory: a..a+length to zero.
*)

@findex MemZero
PROCEDURE MemZero (a: ADDRESS; length: CARDINAL) ;


END MemUtils.
@end example
@page

@node gm2-libs/NumberIO, gm2-libs/OptLib, gm2-libs/MemUtils, Base libraries
@subsection gm2-libs/NumberIO

@example
DEFINITION MODULE NumberIO ;

EXPORT QUALIFIED ReadCard, WriteCard, ReadHex, WriteHex, ReadInt, WriteInt,
                 CardToStr, StrToCard, StrToHex, HexToStr, StrToInt, IntToStr,
                 ReadOct, WriteOct, OctToStr, StrToOct,
                 ReadBin, WriteBin, BinToStr, StrToBin,
                 StrToBinInt, StrToHexInt, StrToOctInt ;


@findex ReadCard
PROCEDURE ReadCard (VAR x: CARDINAL) ;

@findex WriteCard
PROCEDURE WriteCard (x, n: CARDINAL) ;

@findex ReadHex
PROCEDURE ReadHex (VAR x: CARDINAL) ;

@findex WriteHex
PROCEDURE WriteHex (x, n: CARDINAL) ;

@findex ReadInt
PROCEDURE ReadInt (VAR x: INTEGER) ;

@findex WriteInt
PROCEDURE WriteInt (x: INTEGER ; n: CARDINAL) ;

@findex CardToStr
PROCEDURE CardToStr (x, n: CARDINAL ; VAR a: ARRAY OF CHAR) ;

@findex StrToCard
PROCEDURE StrToCard (a: ARRAY OF CHAR ; VAR x: CARDINAL) ;

@findex HexToStr
PROCEDURE HexToStr (x, n: CARDINAL ; VAR a: ARRAY OF CHAR) ;

@findex StrToHex
PROCEDURE StrToHex (a: ARRAY OF CHAR ; VAR x: CARDINAL) ;

@findex IntToStr
PROCEDURE IntToStr (x: INTEGER ; n: CARDINAL ; VAR a: ARRAY OF CHAR) ;

@findex StrToInt
PROCEDURE StrToInt (a: ARRAY OF CHAR ; VAR x: INTEGER) ;

@findex ReadOct
PROCEDURE ReadOct (VAR x: CARDINAL) ;

@findex WriteOct
PROCEDURE WriteOct (x, n: CARDINAL) ;

@findex OctToStr
PROCEDURE OctToStr (x, n: CARDINAL ; VAR a: ARRAY OF CHAR) ;

@findex StrToOct
PROCEDURE StrToOct (a: ARRAY OF CHAR ; VAR x: CARDINAL) ;

@findex ReadBin
PROCEDURE ReadBin (VAR x: CARDINAL) ;

@findex WriteBin
PROCEDURE WriteBin (x, n: CARDINAL) ;

@findex BinToStr
PROCEDURE BinToStr (x, n: CARDINAL ; VAR a: ARRAY OF CHAR) ;

@findex StrToBin
PROCEDURE StrToBin (a: ARRAY OF CHAR ; VAR x: CARDINAL) ;

@findex StrToBinInt
PROCEDURE StrToBinInt (a: ARRAY OF CHAR ; VAR x: INTEGER) ;

@findex StrToHexInt
PROCEDURE StrToHexInt (a: ARRAY OF CHAR ; VAR x: INTEGER) ;

@findex StrToOctInt
PROCEDURE StrToOctInt (a: ARRAY OF CHAR ; VAR x: INTEGER) ;


END NumberIO.
@end example
@page

@node gm2-libs/OptLib, gm2-libs/PushBackInput, gm2-libs/NumberIO, Base libraries
@subsection gm2-libs/OptLib

@example
DEFINITION MODULE OptLib ;

FROM SYSTEM IMPORT ADDRESS ;
FROM DynamicStrings IMPORT String ;

TYPE
@findex Option (type)
   Option ;


(*
   InitOption - constructor for Option.
*)

@findex InitOption
PROCEDURE InitOption (argc: INTEGER; argv: ADDRESS) : Option ;


(*
   KillOption - deconstructor for Option.
*)

@findex KillOption
PROCEDURE KillOption (o: Option) : Option ;


(*
   Dup - duplicate the option array inside, o.
         Notice that this does not duplicate all the contents
         (strings) of argv.
         Shallow copy of the top level indices.
*)

@findex Dup
PROCEDURE Dup (o: Option) : Option ;


(*
   Slice - return a new option which has elements [low:high] from the
           options, o.
*)

@findex Slice
PROCEDURE Slice (o: Option; low, high: INTEGER) : Option ;


(*
   IndexStrCmp - returns the index in the argv array which matches
                 string, s.  -1 is returned if the string is not found.
*)

@findex IndexStrCmp
PROCEDURE IndexStrCmp (o: Option; s: String) : INTEGER ;


(*
   IndexStrNCmp - returns the index in the argv array where the first
                  characters are matched by string, s.
                  -1 is returned if the string is not found.
*)

@findex IndexStrNCmp
PROCEDURE IndexStrNCmp (o: Option; s: String) : INTEGER ;


(*
   ConCat - returns the concatenation of a and b.
*)

@findex ConCat
PROCEDURE ConCat (a, b: Option) : Option ;


(*
   GetArgv - return the argv component of option.
*)

@findex GetArgv
PROCEDURE GetArgv (o: Option) : ADDRESS ;


(*
   GetArgc - return the argc component of option.
*)

@findex GetArgc
PROCEDURE GetArgc (o: Option) : INTEGER ;


END OptLib.
@end example
@page

@node gm2-libs/PushBackInput, gm2-libs/RTExceptions, gm2-libs/OptLib, Base libraries
@subsection gm2-libs/PushBackInput

@example
DEFINITION MODULE PushBackInput ;

FROM FIO IMPORT File ;
FROM DynamicStrings IMPORT String ;

EXPORT QUALIFIED Open, PutCh, GetCh, Error, WarnError, WarnString,
                 Close, SetDebug, GetExitStatus, PutStr,
                 PutString, GetColumnPosition, GetCurrentLine ;


(*
   Open - opens a file for reading.
*)

@findex Open
PROCEDURE Open (a: ARRAY OF CHAR) : File ;


(*
   GetCh - gets a character from either the push back stack or
           from file, f.
*)

@findex GetCh
PROCEDURE GetCh (f: File) : CHAR ;


(*
   PutCh - pushes a character onto the push back stack, it also
           returns the character which has been pushed.
*)

@findex PutCh
PROCEDURE PutCh (ch: CHAR) : CHAR ;


(*
   PutString - pushes a string onto the push back stack.
*)

@findex PutString
PROCEDURE PutString (a: ARRAY OF CHAR) ;


(*
   PutStr - pushes a dynamic string onto the push back stack.
            The string, s, is not deallocated.
*)

@findex PutStr
PROCEDURE PutStr (s: String) ;


(*
   Error - emits an error message with the appropriate file, line combination.
*)

@findex Error
PROCEDURE Error (a: ARRAY OF CHAR) ;


(*
   WarnError - emits an error message with the appropriate file, line combination.
               It does not terminate but when the program finishes an exit status of
               1 will be issued.
*)

@findex WarnError
PROCEDURE WarnError (a: ARRAY OF CHAR) ;


(*
   WarnString - emits an error message with the appropriate file, line combination.
                It does not terminate but when the program finishes an exit status of
                1 will be issued.
*)

@findex WarnString
PROCEDURE WarnString (s: String) ;


(*
   Close - closes the opened file.
*)

@findex Close
PROCEDURE Close (f: File) ;


(*
   GetExitStatus - returns the exit status which will be 1 if any warnings were issued.
*)

@findex GetExitStatus
PROCEDURE GetExitStatus () : CARDINAL ;


(*
   SetDebug - sets the debug flag on or off.
*)

@findex SetDebug
PROCEDURE SetDebug (d: BOOLEAN) ;


(*
   GetColumnPosition - returns the column position of the current character.
*)

@findex GetColumnPosition
PROCEDURE GetColumnPosition () : CARDINAL ;


(*
   GetCurrentLine - returns the current line number.
*)

@findex GetCurrentLine
PROCEDURE GetCurrentLine () : CARDINAL ;


END PushBackInput.
@end example
@page

@node gm2-libs/RTExceptions, gm2-libs/RTint, gm2-libs/PushBackInput, Base libraries
@subsection gm2-libs/RTExceptions

@example
DEFINITION MODULE RTExceptions ;

(* Runtime exception handler routines.  This should
   be considered as a system module for GNU Modula-2
   and allow the compiler to interface with exception
   handling.  *)

FROM SYSTEM IMPORT ADDRESS ;
EXPORT QUALIFIED EHBlock,
                 Raise, SetExceptionBlock, GetExceptionBlock,
                 GetTextBuffer, GetTextBufferSize, GetNumber,
                 InitExceptionBlock, KillExceptionBlock,
                 PushHandler, PopHandler,
                 BaseExceptionsThrow, DefaultErrorCatch,
                 IsInExceptionState, SetExceptionState,
                 SwitchExceptionState, GetBaseExceptionBlock,
                 SetExceptionSource, GetExceptionSource ;

TYPE
@findex EHBlock (type)
   EHBlock ;
@findex ProcedureHandler (type)
   ProcedureHandler = PROCEDURE ;


(*
   Raise - invoke the exception handler associated with, number,
           in the active EHBlock.  It keeps a record of the number
           and message in the EHBlock for later use.
*)

@findex Raise
PROCEDURE Raise (number: CARDINAL;
                 file: ADDRESS; line: CARDINAL;
                 column: CARDINAL; function: ADDRESS;
                 message: ADDRESS) ;


(*
   SetExceptionBlock - sets, source, as the active EHB.
*)

@findex SetExceptionBlock
PROCEDURE SetExceptionBlock (source: EHBlock) ;


(*
   GetExceptionBlock - returns the active EHB.
*)

@findex GetExceptionBlock
PROCEDURE GetExceptionBlock () : EHBlock ;


(*
   GetTextBuffer - returns the address of the EHB buffer.
*)

@findex GetTextBuffer
PROCEDURE GetTextBuffer (e: EHBlock) : ADDRESS ;


(*
   GetTextBufferSize - return the size of the EHB text buffer.
*)

@findex GetTextBufferSize
PROCEDURE GetTextBufferSize (e: EHBlock) : CARDINAL ;


(*
   GetNumber - return the exception number associated with,
               source.
*)

@findex GetNumber
PROCEDURE GetNumber (source: EHBlock) : CARDINAL ;


(*
   InitExceptionBlock - creates and returns a new exception block.
*)

@findex InitExceptionBlock
PROCEDURE InitExceptionBlock () : EHBlock ;


(*
   KillExceptionBlock - destroys the EHB, e, and all its handlers.
*)

@findex KillExceptionBlock
PROCEDURE KillExceptionBlock (e: EHBlock) : EHBlock ;


(*
   PushHandler - install a handler in EHB, e.
*)

@findex PushHandler
PROCEDURE PushHandler (e: EHBlock; number: CARDINAL; p: ProcedureHandler) ;


(*
   PopHandler - removes the handler associated with, number, from
                EHB, e.
*)

@findex PopHandler
PROCEDURE PopHandler (e: EHBlock; number: CARDINAL) ;


(*
   DefaultErrorCatch - displays the current error message in
                       the current exception block and then
                       calls HALT.
*)

@findex DefaultErrorCatch
PROCEDURE DefaultErrorCatch ;


(*
   BaseExceptionsThrow - configures the Modula-2 exceptions to call
                         THROW which in turn can be caught by an
                         exception block.  If this is not called then
                         a Modula-2 exception will simply call an
                         error message routine and then HALT.
*)

@findex BaseExceptionsThrow
PROCEDURE BaseExceptionsThrow ;


(*
   IsInExceptionState - returns TRUE if the program is currently
                        in the exception state.
*)

@findex IsInExceptionState
PROCEDURE IsInExceptionState () : BOOLEAN ;


(*
   SetExceptionState - returns the current exception state and
                       then sets the current exception state to,
                       to.
*)

@findex SetExceptionState
PROCEDURE SetExceptionState (to: BOOLEAN) : BOOLEAN ;


(*
   SwitchExceptionState - assigns, from, with the current exception
                          state and then assigns the current exception
                          to, to.
*)

@findex SwitchExceptionState
PROCEDURE SwitchExceptionState (VAR from: BOOLEAN; to: BOOLEAN) ;


(*
   GetBaseExceptionBlock - returns the initial language exception block
                           created.
*)

@findex GetBaseExceptionBlock
PROCEDURE GetBaseExceptionBlock () : EHBlock ;


(*
   SetExceptionSource - sets the current exception source to, source.
*)

@findex SetExceptionSource
PROCEDURE SetExceptionSource (source: ADDRESS) ;


(*
   GetExceptionSource - returns the current exception source.
*)

@findex GetExceptionSource
PROCEDURE GetExceptionSource () : ADDRESS ;


END RTExceptions.
@end example
@page

@node gm2-libs/RTint, gm2-libs/SArgs, gm2-libs/RTExceptions, Base libraries
@subsection gm2-libs/RTint

@example
DEFINITION MODULE RTint ;

(* Provides users of the COROUTINES library with the
   ability to create interrupt sources based on
   file descriptors and timeouts.  *)

FROM SYSTEM IMPORT ADDRESS ;

TYPE
@findex DispatchVector (type)
   DispatchVector = PROCEDURE (CARDINAL, CARDINAL, ADDRESS) ;


(*
   InitInputVector - returns an interrupt vector which is associated
                     with the file descriptor, fd.
*)

@findex InitInputVector
PROCEDURE InitInputVector (fd: INTEGER; pri: CARDINAL) : CARDINAL ;


(*
   InitOutputVector - returns an interrupt vector which is associated
                      with the file descriptor, fd.
*)

@findex InitOutputVector
PROCEDURE InitOutputVector (fd: INTEGER; pri: CARDINAL) : CARDINAL ;


(*
   InitTimeVector - returns an interrupt vector associated with
                    the relative time.
*)

@findex InitTimeVector
PROCEDURE InitTimeVector (micro, secs: CARDINAL; pri: CARDINAL) : CARDINAL ;


(*
   ReArmTimeVector - reprimes the vector, vec, to deliver an interrupt
                     at the new relative time.
*)

@findex ReArmTimeVector
PROCEDURE ReArmTimeVector (vec: CARDINAL; micro, secs: CARDINAL) ;


(*
   GetTimeVector - assigns, micro, and, secs, with the remaining
                   time before this interrupt will expire.
                   This value is only updated when a Listen
                   occurs.
*)

@findex GetTimeVector
PROCEDURE GetTimeVector (vec: CARDINAL; VAR micro, secs: CARDINAL) ;


(*
   AttachVector - adds the pointer, p, to be associated with the interrupt
                  vector. It returns the previous value attached to this
                  vector.
*)

@findex AttachVector
PROCEDURE AttachVector (vec: CARDINAL; p: ADDRESS) : ADDRESS ;


(*
   IncludeVector - includes, vec, into the dispatcher list of
                   possible interrupt causes.
*)

@findex IncludeVector
PROCEDURE IncludeVector (vec: CARDINAL) ;


(*
   ExcludeVector - excludes, vec, from the dispatcher list of
                   possible interrupt causes.
*)

@findex ExcludeVector
PROCEDURE ExcludeVector (vec: CARDINAL) ;


(*
   Listen - will either block indefinitely (until an interrupt)
            or alteratively will test to see whether any interrupts
            are pending.
            If a pending interrupt was found then, call, is called
            and then this procedure returns.
            It only listens for interrupts > pri.
*)

@findex Listen
PROCEDURE Listen (untilInterrupt: BOOLEAN;
                  call: DispatchVector;
                  pri: CARDINAL) ;


(*
   Init - allows the user to force the initialize order.
*)

@findex Init
PROCEDURE Init ;


END RTint.
@end example
@page

@node gm2-libs/SArgs, gm2-libs/SCmdArgs, gm2-libs/RTint, Base libraries
@subsection gm2-libs/SArgs

@example
DEFINITION MODULE SArgs ;

FROM DynamicStrings IMPORT String ;
EXPORT QUALIFIED GetArg, Narg ;


(*
   GetArg - returns the nth argument from the command line.
            The success of the operation is returned.
            If TRUE is returned then the string, s, contains a
            new string, otherwise s is set to NIL.
*)

@findex GetArg
PROCEDURE GetArg (VAR s: String ; n: CARDINAL) : BOOLEAN ;


(*
   Narg - returns the number of arguments available from
          command line.
*)

@findex Narg
PROCEDURE Narg() : CARDINAL ;


END SArgs.
@end example
@page

@node gm2-libs/SCmdArgs, gm2-libs/SEnvironment, gm2-libs/SArgs, Base libraries
@subsection gm2-libs/SCmdArgs

@example
DEFINITION MODULE SCmdArgs ;

FROM DynamicStrings IMPORT String ;

EXPORT QUALIFIED GetArg, Narg ;


(*
   GetArg - returns the nth argument from the command line, CmdLine
            the success of the operation is returned.
*)

@findex GetArg
PROCEDURE GetArg (CmdLine: String;
                  n: CARDINAL; VAR Argi: String) : BOOLEAN ;


(*
   Narg - returns the number of arguments available from
          command line, CmdLine.
*)

@findex Narg
PROCEDURE Narg (CmdLine: String) : CARDINAL ;


END SCmdArgs.
@end example
@page

@node gm2-libs/SEnvironment, gm2-libs/SFIO, gm2-libs/SCmdArgs, Base libraries
@subsection gm2-libs/SEnvironment

@example
DEFINITION MODULE SEnvironment ;


FROM DynamicStrings IMPORT String ;
EXPORT QUALIFIED GetEnvironment ;


(*
   GetEnvironment - gets the environment variable Env and places
      	       	    a copy of its value into String, dest.
                    It returns TRUE if the string Env was found in
                    the processes environment.
*)

@findex GetEnvironment
PROCEDURE GetEnvironment (Env: String;
                          VAR dest: String) : BOOLEAN ;


(*
   PutEnvironment - change or add an environment variable definition EnvDef.
                    TRUE is returned if the environment variable was
                    set or changed successfully.
*)

@findex PutEnvironment
PROCEDURE PutEnvironment (EnvDef: String) : BOOLEAN ;


END SEnvironment.
@end example
@page

@node gm2-libs/SFIO, gm2-libs/SMathLib0, gm2-libs/SEnvironment, Base libraries
@subsection gm2-libs/SFIO

@example
DEFINITION MODULE SFIO ;

FROM DynamicStrings IMPORT String ;
FROM FIO IMPORT File ;

EXPORT QUALIFIED OpenToRead, OpenToWrite, OpenForRandom, Exists, WriteS, ReadS ;


(*
   Exists - returns TRUE if a file named, fname exists for reading.
*)

@findex Exists
PROCEDURE Exists (fname: String) : BOOLEAN ;


(*
   OpenToRead - attempts to open a file, fname, for reading and
                it returns this file.
                The success of this operation can be checked by
                calling IsNoError.
*)

@findex OpenToRead
PROCEDURE OpenToRead (fname: String) : File ;


(*
   OpenToWrite - attempts to open a file, fname, for write and
                 it returns this file.
                 The success of this operation can be checked by
                 calling IsNoError.
*)

@findex OpenToWrite
PROCEDURE OpenToWrite (fname: String) : File ;


(*
   OpenForRandom - attempts to open a file, fname, for random access
                   read or write and it returns this file.
                   The success of this operation can be checked by
                   calling IsNoError.
                   towrite, determines whether the file should be
                   opened for writing or reading.
                   if towrite is TRUE or whether the previous file should
                   be left alone, allowing this descriptor to seek
                   and modify an existing file.
*)

@findex OpenForRandom
PROCEDURE OpenForRandom (fname: String; towrite, newfile: BOOLEAN) : File ;


(*
   WriteS - writes a string, s, to, file. It returns the String, s.
*)

@findex WriteS
PROCEDURE WriteS (file: File; s: String) : String ;


(*
   ReadS - reads a string, s, from, file. It returns the String, s.
           It stops reading the string at the end of line or end of file.
           It consumes the newline at the end of line but does not place
           this into the returned string.
*)

@findex ReadS
PROCEDURE ReadS (file: File) : String ;


END SFIO.
@end example
@page

@node gm2-libs/SMathLib0, gm2-libs/SYSTEM, gm2-libs/SFIO, Base libraries
@subsection gm2-libs/SMathLib0

@example
DEFINITION MODULE SMathLib0 ;

CONST
   pi   = 3.1415926535897932384626433832795028841972;
   exp1 = 2.7182818284590452353602874713526624977572;


@findex sqrt
PROCEDURE __BUILTIN__ sqrt (x: SHORTREAL) : SHORTREAL ;
@findex exp
PROCEDURE exp (x: SHORTREAL) : SHORTREAL ;
@findex ln
PROCEDURE ln (x: SHORTREAL) : SHORTREAL ;
@findex sin
PROCEDURE __BUILTIN__ sin (x: SHORTREAL) : SHORTREAL ;
@findex cos
PROCEDURE __BUILTIN__ cos (x: SHORTREAL) : SHORTREAL ;
@findex tan
PROCEDURE tan (x: SHORTREAL) : SHORTREAL ;
@findex arctan
PROCEDURE arctan (x: SHORTREAL) : SHORTREAL ;
@findex entier
PROCEDURE entier (x: SHORTREAL) : INTEGER ;


END SMathLib0.
@end example
@page

@node gm2-libs/SYSTEM, gm2-libs/Scan, gm2-libs/SMathLib0, Base libraries
@subsection gm2-libs/SYSTEM

@example
DEFINITION MODULE SYSTEM ;

EXPORT QUALIFIED BITSPERBYTE, BYTESPERWORD,
                 ADDRESS, WORD, BYTE, CSIZE_T, CSSIZE_T, (* 
                 Target specific data types.  *)
                 ADR, TSIZE, ROTATE, SHIFT, THROW, TBITSIZE ;
                 (* SIZE is also exported if -fpim2 is used.  *)

CONST
@findex BITSPERBYTE (const)
  BITSPERBYTE   = __ATTRIBUTE__ __BUILTIN__ ((BITS_PER_UNIT)) ;
@findex BYTESPERWORD (const)
  BYTESPERWORD  = __ATTRIBUTE__ __BUILTIN__ ((UNITS_PER_WORD)) ;

(* Note that the full list of system and sized datatypes include:
   LOC, WORD, BYTE, ADDRESS,

   (and the non language standard target types)

   INTEGER8, INTEGER16, INTEGER32, INTEGER64,
   CARDINAL8, CARDINAL16, CARDINAL32, CARDINAL64,
   WORD16, WORD32, WORD64, BITSET8, BITSET16,
   BITSET32, REAL32, REAL64, REAL128, COMPLEX32,
   COMPLEX64, COMPLEX128, CSIZE_T, CSSIZE_T.

   Also note that the non-standard data types will
   move into another module in the future.  *)


(* The following types are supported on this target:
TYPE
   (* Target specific data types.  *)
*)


(*
   all the functions below are declared internally to gm2
   ======================================================

@findex ADR
PROCEDURE ADR (VAR v: <anytype>): ADDRESS;
  (* Returns the address of variable v. *)

@findex SIZE
PROCEDURE SIZE (v: <type>) : ZType;
  (* Returns the number of BYTES used to store a v of
     any specified <type>.  Only available if -fpim2 is used.
  *)

@findex TSIZE
PROCEDURE TSIZE (<type>) : CARDINAL;
  (* Returns the number of BYTES used to store a value of the
     specified <type>.
  *)

@findex ROTATE
PROCEDURE ROTATE (val: <a set type>;
                  num: INTEGER): <type of first parameter>;
  (* Returns a bit sequence obtained from val by rotating up/right
     or down/right by the absolute value of num.  The direction is
     down/right if the sign of num is negative, otherwise the direction
     is up/left.
  *)

@findex SHIFT
PROCEDURE SHIFT (val: <a set type>;
                 num: INTEGER): <type of first parameter>;
  (* Returns a bit sequence obtained from val by shifting up/left
     or down/right by the absolute value of num, introducing
     zeros as necessary.  The direction is down/right if the sign of
     num is negative, otherwise the direction is up/left.
  *)

@findex THROW
PROCEDURE THROW (i: INTEGER) ;
  (*
     THROW is a GNU extension and was not part of the PIM or ISO
     standards.  It throws an exception which will be caught by the
     EXCEPT block (assuming it exists).  This is a compiler builtin
     function which interfaces to the GCC exception handling runtime
     system.
     GCC uses the term throw, hence the naming distinction between
     the GCC builtin and the Modula-2 runtime library procedure Raise.
     The later library procedure Raise will call SYSTEM.THROW after
     performing various housekeeping activities.
  *)

@findex TBITSIZE
PROCEDURE TBITSIZE (<type>) : CARDINAL ;
  (* Returns the minimum number of bits necessary to represent
     <type>.  This procedure function is only useful for determining
     the number of bits used for any type field within a packed RECORD.
     It is not particularly useful elsewhere since <type> might be
     optimized for speed, for example a BOOLEAN could occupy a WORD.
  *)
*)

(* The following procedures are invoked by GNU Modula-2 to
   shift non word sized set types. They are not strictly part
   of the core PIM Modula-2, however they are used
   to implement the SHIFT procedure defined above,
   which are in turn used by the Logitech compatible libraries.

   Users will access these procedures by using the procedure
   SHIFT above and GNU Modula-2 will map SHIFT onto one of
   the following procedures.
*)

(*
   ShiftVal - is a runtime procedure whose job is to implement
              the SHIFT procedure of ISO SYSTEM. GNU Modula-2 will
              inline a SHIFT of a single WORD sized set and will only
              call this routine for larger sets.
*)

@findex ShiftVal
PROCEDURE ShiftVal (VAR s, d: ARRAY OF BITSET;
                    SetSizeInBits: CARDINAL;
                    ShiftCount: INTEGER) ;


(*
   ShiftLeft - performs the shift left for a multi word set.
               This procedure might be called by the back end of
               GNU Modula-2 depending whether amount is known at
               compile time.
*)

@findex ShiftLeft
PROCEDURE ShiftLeft (VAR s, d: ARRAY OF BITSET;
                     SetSizeInBits: CARDINAL;
                     ShiftCount: CARDINAL) ;

(*
   ShiftRight - performs the shift left for a multi word set.
                This procedure might be called by the back end of
                GNU Modula-2 depending whether amount is known at
                compile time.
*)

@findex ShiftRight
PROCEDURE ShiftRight (VAR s, d: ARRAY OF BITSET;
                      SetSizeInBits: CARDINAL;
                      ShiftCount: CARDINAL) ;


(*
   RotateVal - is a runtime procedure whose job is to implement
               the ROTATE procedure of ISO SYSTEM. GNU Modula-2 will
               inline a ROTATE of a single WORD (or less)
               sized set and will only call this routine for larger
               sets.
*)

@findex RotateVal
PROCEDURE RotateVal (VAR s, d: ARRAY OF BITSET;
                     SetSizeInBits: CARDINAL;
                     RotateCount: INTEGER) ;


(*
   RotateLeft - performs the rotate left for a multi word set.
                This procedure might be called by the back end of
                GNU Modula-2 depending whether amount is known at
                compile time.
*)

@findex RotateLeft
PROCEDURE RotateLeft (VAR s, d: ARRAY OF BITSET;
                      SetSizeInBits: CARDINAL;
                      RotateCount: CARDINAL) ;


(*
   RotateRight - performs the rotate right for a multi word set.
                 This procedure might be called by the back end of
                 GNU Modula-2 depending whether amount is known at
                 compile time.
*)

@findex RotateRight
PROCEDURE RotateRight (VAR s, d: ARRAY OF BITSET;
                       SetSizeInBits: CARDINAL;
                       RotateCount: CARDINAL) ;


END SYSTEM.
@end example
@page

@node gm2-libs/Scan, gm2-libs/Selective, gm2-libs/SYSTEM, Base libraries
@subsection gm2-libs/Scan

@example
DEFINITION MODULE Scan ;

(* Provides a primitive symbol fetching from input.
   Symbols are delimited by spaces and tabs.
   Limitation only allows one source file at
   a time to deliver symbols.  *)


EXPORT QUALIFIED GetNextSymbol, WriteError,
                 OpenSource, CloseSource,
                 TerminateOnError, DefineComments ;


(* OpenSource - opens a source file for reading.                  *)

@findex OpenSource
PROCEDURE OpenSource (a: ARRAY OF CHAR) : BOOLEAN ;


(* CloseSource - closes the current source file from reading.     *)

@findex CloseSource
PROCEDURE CloseSource ;


(* GetNextSymbol gets the next source symbol and returns it in a. *)

@findex GetNextSymbol
PROCEDURE GetNextSymbol (VAR a: ARRAY OF CHAR) ;


(* WriteError writes a message, a, under the source line, which   *)
(* attempts to pinpoint the Symbol at fault.                      *)

@findex WriteError
PROCEDURE WriteError (a: ARRAY OF CHAR) ;


(*
   TerminateOnError - exits with status 1 if we call WriteError.
*)

@findex TerminateOnError
PROCEDURE TerminateOnError ;


(*
   DefineComments - defines the start of comments within the source
                    file.

                    The characters in Start define the comment start
                    and characters in End define the end.
                    The BOOLEAN eoln determine whether the comment
                    is terminated by end of line. If eoln is TRUE
                    then End is ignored.

                    If this procedure is never called then no comments
                    are allowed.
*)

@findex DefineComments
PROCEDURE DefineComments (Start, End: ARRAY OF CHAR; eoln: BOOLEAN) ;


END Scan.
@end example
@page

@node gm2-libs/Selective, gm2-libs/StdIO, gm2-libs/Scan, Base libraries
@subsection gm2-libs/Selective

@example
DEFINITION MODULE Selective ;

FROM SYSTEM IMPORT ADDRESS ;

EXPORT QUALIFIED SetOfFd, Timeval,
                 InitSet, KillSet, InitTime, KillTime,
                 GetTime, SetTime,
                 FdZero, FdSet, FdClr, FdIsSet, Select,
                 MaxFdsPlusOne, WriteCharRaw, ReadCharRaw,
                 GetTimeOfDay ;

TYPE
@findex SetOfFd (type)
   SetOfFd = ADDRESS ;    (* Hidden type in Selective.c *)
@findex Timeval (type)
   Timeval = ADDRESS ;    (* Hidden type in Selective.c *)


@findex Select
PROCEDURE Select (nooffds: CARDINAL;
                  readfds, writefds, exceptfds: SetOfFd;
                  timeout: Timeval) : INTEGER ;

@findex InitTime
PROCEDURE InitTime (sec, usec: CARDINAL) : Timeval ;
@findex KillTime
PROCEDURE KillTime (t: Timeval) : Timeval ;
@findex GetTime
PROCEDURE GetTime (t: Timeval; VAR sec, usec: CARDINAL) ;
@findex SetTime
PROCEDURE SetTime (t: Timeval; sec, usec: CARDINAL) ;
@findex InitSet
PROCEDURE InitSet () : SetOfFd ;
@findex KillSet
PROCEDURE KillSet (s: SetOfFd) : SetOfFd ;
@findex FdZero
PROCEDURE FdZero (s: SetOfFd) ;
@findex FdSet
PROCEDURE FdSet (fd: INTEGER; s: SetOfFd) ;
@findex FdClr
PROCEDURE FdClr (fd: INTEGER; s: SetOfFd) ;
@findex FdIsSet
PROCEDURE FdIsSet (fd: INTEGER; s: SetOfFd) : BOOLEAN ;
@findex MaxFdsPlusOne
PROCEDURE MaxFdsPlusOne (a, b: INTEGER) : INTEGER ;

(* you must use the raw routines with select - not the FIO buffered routines *)
@findex WriteCharRaw
PROCEDURE WriteCharRaw (fd: INTEGER; ch: CHAR) ;
@findex ReadCharRaw
PROCEDURE ReadCharRaw (fd: INTEGER) : CHAR ;

(*
   GetTimeOfDay - fills in a record, Timeval, filled in with the
                  current system time in seconds and microseconds.
                  It returns zero (see man 3p gettimeofday)
*)

@findex GetTimeOfDay
PROCEDURE GetTimeOfDay (tv: Timeval) : INTEGER ;


END Selective.
@end example
@page

@node gm2-libs/StdIO, gm2-libs/Storage, gm2-libs/Selective, Base libraries
@subsection gm2-libs/StdIO

@example
DEFINITION MODULE StdIO ;

EXPORT QUALIFIED ProcRead, ProcWrite,
                 Read, Write,
                 PushOutput, PopOutput, GetCurrentOutput,
                 PushInput, PopInput, GetCurrentInput ;


TYPE
@findex ProcWrite (type)
   ProcWrite = PROCEDURE (CHAR) ;
@findex ProcRead (type)
   ProcRead  = PROCEDURE (VAR CHAR) ;


(*
   Read - is the generic procedure that all higher application layers
          should use to receive a character.
*)

@findex Read
PROCEDURE Read (VAR ch: CHAR) ;


(*
   Write - is the generic procedure that all higher application layers
           should use to emit a character.
*)

@findex Write
PROCEDURE Write (ch: CHAR) ;


(*
   PushOutput - pushes the current Write procedure onto a stack,
                any future references to Write will actually invoke
                procedure, p.
*)

@findex PushOutput
PROCEDURE PushOutput (p: ProcWrite) ;


(*
   PopOutput - restores Write to use the previous output procedure.
*)

@findex PopOutput
PROCEDURE PopOutput ;


(*
   GetCurrentOutput - returns the current output procedure.
*)

@findex GetCurrentOutput
PROCEDURE GetCurrentOutput () : ProcWrite ;


(*
   PushInput - pushes the current Read procedure onto a stack,
               any future references to Read will actually invoke
               procedure, p.
*)

@findex PushInput
PROCEDURE PushInput (p: ProcRead) ;


(*
   PopInput - restores Write to use the previous output procedure.
*)

@findex PopInput
PROCEDURE PopInput ;


(*
   GetCurrentInput - returns the current input procedure.
*)

@findex GetCurrentInput
PROCEDURE GetCurrentInput () : ProcRead ;


END StdIO.
@end example
@page

@node gm2-libs/Storage, gm2-libs/StrCase, gm2-libs/StdIO, Base libraries
@subsection gm2-libs/Storage

@example
DEFINITION MODULE Storage ;

FROM SYSTEM IMPORT ADDRESS ;

EXPORT QUALIFIED ALLOCATE, DEALLOCATE, REALLOCATE, Available ;



(*
   ALLOCATE - attempt to allocate memory from the heap.
              NIL is returned in, a, if ALLOCATE fails.
*)

@findex ALLOCATE
PROCEDURE ALLOCATE (VAR a: ADDRESS ; Size: CARDINAL) ;


(*
   DEALLOCATE - return, Size, bytes to the heap.
                The variable, a, is set to NIL.
*)

@findex DEALLOCATE
PROCEDURE DEALLOCATE (VAR a: ADDRESS ; Size: CARDINAL) ;


(*
   REALLOCATE - attempts to reallocate storage. The address,
                a, should either be NIL in which case ALLOCATE
                is called, or alternatively it should have already
                been initialized by ALLOCATE. The allocated storage
                is resized accordingly.
*)

@findex REALLOCATE
PROCEDURE REALLOCATE (VAR a: ADDRESS; Size: CARDINAL) ;


(*
   Available - returns TRUE if, Size, bytes can be allocated.
*)

@findex Available
PROCEDURE Available (Size: CARDINAL) : BOOLEAN ;


END Storage.
@end example
@page

@node gm2-libs/StrCase, gm2-libs/StrIO, gm2-libs/Storage, Base libraries
@subsection gm2-libs/StrCase

@example
DEFINITION MODULE StrCase ;


EXPORT QUALIFIED StrToUpperCase, StrToLowerCase, Cap, Lower ;


(*
   StrToUpperCase - converts string, a, to uppercase returning the
                    result in, b.
*)

@findex StrToUpperCase
PROCEDURE StrToUpperCase (a: ARRAY OF CHAR ; VAR b: ARRAY OF CHAR) ;


(*
   StrToLowerCase - converts string, a, to lowercase returning the
                    result in, b.
*)

@findex StrToLowerCase
PROCEDURE StrToLowerCase (a: ARRAY OF CHAR ; VAR b: ARRAY OF CHAR) ;


(*
   Cap - converts a lower case character into a capital character.
         If the character is not a lower case character 'a'..'z'
         then the character is simply returned unaltered.
*)

@findex Cap
PROCEDURE Cap (ch: CHAR) : CHAR ;


(*
   Lower - converts an upper case character into a lower case character.
           If the character is not an upper case character 'A'..'Z'
           then the character is simply returned unaltered.
*)

@findex Lower
PROCEDURE Lower (ch: CHAR) : CHAR ;


END StrCase.
@end example
@page

@node gm2-libs/StrIO, gm2-libs/StrLib, gm2-libs/StrCase, Base libraries
@subsection gm2-libs/StrIO

@example
DEFINITION MODULE StrIO ;

EXPORT QUALIFIED ReadString, WriteString,
                 WriteLn ;


(*
   WriteLn - writes a carriage return and a newline
             character.
*)

@findex WriteLn
PROCEDURE WriteLn ;


(*
   ReadString - reads a sequence of characters into a string.
                Line editing accepts Del, Ctrl H, Ctrl W and
                Ctrl U.
*)

@findex ReadString
PROCEDURE ReadString (VAR a: ARRAY OF CHAR) ;


(*
   WriteString - writes a string to the default output.
*)

@findex WriteString
PROCEDURE WriteString (a: ARRAY OF CHAR) ;


END StrIO.
@end example
@page

@node gm2-libs/StrLib, gm2-libs/StringConvert, gm2-libs/StrIO, Base libraries
@subsection gm2-libs/StrLib

@example
DEFINITION MODULE StrLib ;

EXPORT QUALIFIED StrConCat, StrLen, StrCopy, StrEqual, StrLess,
      	       	 IsSubString, StrRemoveWhitePrefix ;


(*
   StrConCat - combines a and b into c.
*)

@findex StrConCat
PROCEDURE StrConCat (a, b: ARRAY OF CHAR; VAR c: ARRAY OF CHAR) ;


(*
   StrLess - returns TRUE if string, a, alphabetically occurs before
             string, b.
*)

@findex StrLess
PROCEDURE StrLess (a, b: ARRAY OF CHAR) : BOOLEAN ;


(*
   StrEqual - performs a = b on two strings.
*)

@findex StrEqual
PROCEDURE StrEqual (a, b: ARRAY OF CHAR) : BOOLEAN ;


(*
   StrLen - returns the length of string, a.
*)

@findex StrLen
PROCEDURE StrLen (a: ARRAY OF CHAR) : CARDINAL ;


(*
   StrCopy - copy string src into string dest providing dest is large enough.
             If dest is smaller than a then src then the string is truncated when
             dest is full.  Add a nul character if there is room in dest.
*)

@findex StrCopy
PROCEDURE StrCopy (src: ARRAY OF CHAR ; VAR dest: ARRAY OF CHAR) ;


(*
   IsSubString - returns true if b is a subcomponent of a.
*)

@findex IsSubString
PROCEDURE IsSubString (a, b: ARRAY OF CHAR) : BOOLEAN ;


(*
   StrRemoveWhitePrefix - copies string, into string, b, excluding any white
                          space infront of a.
*)

@findex StrRemoveWhitePrefix
PROCEDURE StrRemoveWhitePrefix (a: ARRAY OF CHAR; VAR b: ARRAY OF CHAR) ;


END StrLib.
@end example
@page

@node gm2-libs/StringConvert, gm2-libs/SysExceptions, gm2-libs/StrLib, Base libraries
@subsection gm2-libs/StringConvert

@example
DEFINITION MODULE StringConvert ;

FROM DynamicStrings IMPORT String ;
EXPORT QUALIFIED IntegerToString, StringToInteger,
                 StringToLongInteger, LongIntegerToString,
                 StringToCardinal, CardinalToString,
                 StringToLongCardinal, LongCardinalToString,
                 StringToShortCardinal, ShortCardinalToString,
                 StringToLongreal, LongrealToString,
                 ToSigFig,
                 stoi, itos, ctos, stoc, hstoi, ostoi, bstoi,
                 hstoc, ostoc, bstoc,
                 stor, stolr ;


(*
   IntegerToString - converts INTEGER, i, into a String. The field with
                     can be specified if non zero. Leading characters
                     are defined by padding and this function will
                     prepend a + if sign is set to TRUE.
                     The base allows the caller to generate binary,
                     octal, decimal, hexidecimal numbers.
                     The value of lower is only used when hexidecimal
                     numbers are generated and if TRUE then digits
                     abcdef are used, and if FALSE then ABCDEF are used.
*)

@findex IntegerToString
PROCEDURE IntegerToString (i: INTEGER; width: CARDINAL; padding: CHAR; sign: BOOLEAN;
                           base: CARDINAL; lower: BOOLEAN) : String ;


(*
   CardinalToString - converts CARDINAL, c, into a String. The field
                      width can be specified if non zero. Leading
                      characters are defined by padding.
                      The base allows the caller to generate binary,
                      octal, decimal, hexidecimal numbers.
                      The value of lower is only used when hexidecimal
                      numbers are generated and if TRUE then digits
                      abcdef are used, and if FALSE then ABCDEF are used.
*)

@findex CardinalToString
PROCEDURE CardinalToString (c: CARDINAL; width: CARDINAL; padding: CHAR;
                            base: CARDINAL; lower: BOOLEAN) : String ;


(*
   StringToInteger - converts a string, s, of, base, into an INTEGER.
                     Leading white space is ignored. It stops converting
                     when either the string is exhausted or if an illegal
                     numeral is found.
                     The parameter found is set TRUE if a number was found.
*)

@findex StringToInteger
PROCEDURE StringToInteger (s: String; base: CARDINAL; VAR found: BOOLEAN) : INTEGER ;


(*
   StringToCardinal - converts a string, s, of, base, into a CARDINAL.
                      Leading white space is ignored. It stops converting
                      when either the string is exhausted or if an illegal
                      numeral is found.
                      The parameter found is set TRUE if a number was found.
*)

@findex StringToCardinal
PROCEDURE StringToCardinal (s: String; base: CARDINAL; VAR found: BOOLEAN) : CARDINAL ;


(*
   LongIntegerToString - converts LONGINT, i, into a String. The field with
                         can be specified if non zero. Leading characters
                         are defined by padding and this function will
                         prepend a + if sign is set to TRUE.
                         The base allows the caller to generate binary,
                         octal, decimal, hexidecimal numbers.
                         The value of lower is only used when hexidecimal
                         numbers are generated and if TRUE then digits
                         abcdef are used, and if FALSE then ABCDEF are used.
*)

@findex LongIntegerToString
PROCEDURE LongIntegerToString (i: LONGINT; width: CARDINAL; padding: CHAR;
                               sign: BOOLEAN; base: CARDINAL; lower: BOOLEAN) : String ;



(*
   StringToLongInteger - converts a string, s, of, base, into an LONGINT.
                         Leading white space is ignored. It stops converting
                         when either the string is exhausted or if an illegal
                         numeral is found.
                         The parameter found is set TRUE if a number was found.
*)

@findex StringToLongInteger
PROCEDURE StringToLongInteger (s: String; base: CARDINAL; VAR found: BOOLEAN) : LONGINT ;


(*
   LongCardinalToString - converts LONGCARD, c, into a String. The field
                          width can be specified if non zero. Leading
                          characters are defined by padding.
                          The base allows the caller to generate binary,
                          octal, decimal, hexidecimal numbers.
                          The value of lower is only used when hexidecimal
                          numbers are generated and if TRUE then digits
                          abcdef are used, and if FALSE then ABCDEF are used.
*)

@findex LongCardinalToString
PROCEDURE LongCardinalToString (c: LONGCARD; width: CARDINAL; padding: CHAR;
                                base: CARDINAL; lower: BOOLEAN) : String ;


(*
   StringToLongCardinal - converts a string, s, of, base, into a LONGCARD.
                          Leading white space is ignored. It stops converting
                          when either the string is exhausted or if an illegal
                          numeral is found.
                          The parameter found is set TRUE if a number was found.
*)

@findex StringToLongCardinal
PROCEDURE StringToLongCardinal (s: String; base: CARDINAL; VAR found: BOOLEAN) : LONGCARD ;


(*
   ShortCardinalToString - converts SHORTCARD, c, into a String. The field
                           width can be specified if non zero. Leading
                           characters are defined by padding.
                           The base allows the caller to generate binary,
                           octal, decimal, hexidecimal numbers.
                           The value of lower is only used when hexidecimal
                           numbers are generated and if TRUE then digits
                           abcdef are used, and if FALSE then ABCDEF are used.
*)

@findex ShortCardinalToString
PROCEDURE ShortCardinalToString (c: SHORTCARD; width: CARDINAL; padding: CHAR;
                                 base: CARDINAL; lower: BOOLEAN) : String ;


(*
   StringToShortCardinal - converts a string, s, of, base, into a SHORTCARD.
                           Leading white space is ignored. It stops converting
                           when either the string is exhausted or if an illegal
                           numeral is found.
                           The parameter found is set TRUE if a number was found.
*)

@findex StringToShortCardinal
PROCEDURE StringToShortCardinal (s: String; base: CARDINAL;
                                 VAR found: BOOLEAN) : SHORTCARD ;


(*
   stoi - decimal string to INTEGER
*)

@findex stoi
PROCEDURE stoi (s: String) : INTEGER ;


(*
   itos - integer to decimal string.
*)

@findex itos
PROCEDURE itos (i: INTEGER; width: CARDINAL; padding: CHAR; sign: BOOLEAN) : String ;


(*
   ctos - cardinal to decimal string.
*)

@findex ctos
PROCEDURE ctos (c: CARDINAL; width: CARDINAL; padding: CHAR) : String ;


(*
   stoc - decimal string to CARDINAL
*)

@findex stoc
PROCEDURE stoc (s: String) : CARDINAL ;


(*
   hstoi - hexidecimal string to INTEGER
*)

@findex hstoi
PROCEDURE hstoi (s: String) : INTEGER ;


(*
   ostoi - octal string to INTEGER
*)

@findex ostoi
PROCEDURE ostoi (s: String) : INTEGER ;


(*
   bstoi - binary string to INTEGER
*)

@findex bstoi
PROCEDURE bstoi (s: String) : INTEGER ;


(*
   hstoc - hexidecimal string to CARDINAL
*)

@findex hstoc
PROCEDURE hstoc (s: String) : CARDINAL ;


(*
   ostoc - octal string to CARDINAL
*)

@findex ostoc
PROCEDURE ostoc (s: String) : CARDINAL ;


(*
   bstoc - binary string to CARDINAL
*)

@findex bstoc
PROCEDURE bstoc (s: String) : CARDINAL ;


(*
   StringToLongreal - returns a LONGREAL and sets found to TRUE
                      if a legal number is seen.
*)

@findex StringToLongreal
PROCEDURE StringToLongreal (s: String; VAR found: BOOLEAN) : LONGREAL ;


(*
   LongrealToString - converts a LONGREAL number, Real, which has,
                      TotalWidth, and FractionWidth into a string.

                      So for example:

                      LongrealToString(1.0, 4, 2)  -> '1.00'
                      LongrealToString(12.3, 5, 2) -> '12.30'
                      LongrealToString(12.3, 6, 2) -> ' 12.30'
                      LongrealToString(12.3, 6, 3) -> '12.300'

                      if total width is too small then the fraction
                      becomes truncated.

                      LongrealToString(12.3, 5, 3) -> '12.30'

                      If TotalWidth is 0 then the function
                      will return the value of x which is converted
                      into as a fixed point number with exhaustive
                      precision.
*)

@findex LongrealToString
PROCEDURE LongrealToString (x: LONGREAL;
                            TotalWidth, FractionWidth: CARDINAL) : String ;


(*
   stor - returns a REAL given a string.
*)

@findex stor
PROCEDURE stor (s: String) : REAL ;


(*
   stolr - returns a LONGREAL given a string.
*)

@findex stolr
PROCEDURE stolr (s: String) : LONGREAL ;


(*
   ToSigFig - returns a floating point or base 10 integer
              string which is accurate to, n, significant
              figures.  It will return a new String
              and, s, will be destroyed.


              So:  12.345

              rounded to the following significant figures yields

              5      12.345
              4      12.34
              3      12.3
              2      12
              1      10
*)

@findex ToSigFig
PROCEDURE ToSigFig (s: String; n: CARDINAL) : String ;


(*
   ToDecimalPlaces - returns a floating point or base 10 integer
                     string which is accurate to, n, decimal
                     places.  It will return a new String
                     and, s, will be destroyed.
                     Decimal places yields, n, digits after
                     the .

                     So:  12.345

                     rounded to the following decimal places yields

                     5      12.34500
                     4      12.3450
                     3      12.345
                     2      12.34
                     1      12.3
*)

@findex ToDecimalPlaces
PROCEDURE ToDecimalPlaces (s: String; n: CARDINAL) : String ;


END StringConvert.
@end example
@page

@node gm2-libs/SysExceptions, gm2-libs/SysStorage, gm2-libs/StringConvert, Base libraries
@subsection gm2-libs/SysExceptions

@example
DEFINITION MODULE SysExceptions ;

(* Provides a mechanism for the underlying libraries to
   configure the exception routines.  This mechanism
   is used by both the ISO and PIM libraries.
   It is written to be ISO compliant and this also
   allows for mixed dialect projects.  *)

FROM SYSTEM IMPORT ADDRESS ;

TYPE
@findex PROCEXCEPTION (type)
   PROCEXCEPTION = PROCEDURE (ADDRESS) ;

@findex InitExceptionHandlers
PROCEDURE InitExceptionHandlers (indexf, range, casef, invalidloc,
                                 function, wholevalue, wholediv,
                                 realvalue, realdiv, complexvalue,
                                 complexdiv, protection, systemf,
                                 coroutine, exception: PROCEXCEPTION) ;


END SysExceptions.
@end example
@page

@node gm2-libs/SysStorage, gm2-libs/TimeString, gm2-libs/SysExceptions, Base libraries
@subsection gm2-libs/SysStorage

@example
DEFINITION MODULE SysStorage ;

(*  Provides dynamic allocation for the system components.
    This allows the application to use the traditional Storage module
    which can be handled differently.  *)

FROM SYSTEM IMPORT ADDRESS ;
EXPORT QUALIFIED ALLOCATE, DEALLOCATE, REALLOCATE, Available, Init ;


(*
   ALLOCATE - attempt to allocate memory from the heap.
              NIL is returned in, a, if ALLOCATE fails.
*)

@findex ALLOCATE
PROCEDURE ALLOCATE (VAR a: ADDRESS ; size: CARDINAL) ;


(*
   DEALLOCATE - return, size, bytes to the heap.
                The variable, a, is set to NIL.
*)

@findex DEALLOCATE
PROCEDURE DEALLOCATE (VAR a: ADDRESS ; size: CARDINAL) ;


(*
   REALLOCATE - attempts to reallocate storage. The address,
                a, should either be NIL in which case ALLOCATE
                is called, or alternatively it should have already
                been initialized by ALLOCATE. The allocated storage
                is resized accordingly.
*)

@findex REALLOCATE
PROCEDURE REALLOCATE (VAR a: ADDRESS; size: CARDINAL) ;


(*
   Available - returns TRUE if, size, bytes can be allocated.
*)

@findex Available
PROCEDURE Available (size: CARDINAL) : BOOLEAN;


(*
   Init - initializes the heap.
          This does nothing on a GNU/Linux system.
          But it remains here since it might be used in an
          embedded system.
*)

@findex Init
PROCEDURE Init ;


END SysStorage.
@end example
@page

@node gm2-libs/TimeString, gm2-libs/UnixArgs, gm2-libs/SysStorage, Base libraries
@subsection gm2-libs/TimeString

@example
DEFINITION MODULE TimeString ;

EXPORT QUALIFIED GetTimeString ;


(*
   GetTimeString - places the time in ascii format into array, a.

*)

@findex GetTimeString
PROCEDURE GetTimeString (VAR a: ARRAY OF CHAR) ;


END TimeString.
@end example
@page

@node gm2-libs/UnixArgs, gm2-libs/cbuiltin, gm2-libs/TimeString, Base libraries
@subsection gm2-libs/UnixArgs

@example
DEFINITION MODULE UnixArgs ;

FROM SYSTEM IMPORT ADDRESS ;

EXPORT QUALIFIED GetArgC, GetArgV, GetEnvV ;

@findex GetArgC
PROCEDURE GetArgC () : INTEGER ;
@findex GetArgV
PROCEDURE GetArgV () : ADDRESS ;
@findex GetEnvV
PROCEDURE GetEnvV () : ADDRESS ;


END UnixArgs.
@end example
@page

@node gm2-libs/cbuiltin, gm2-libs/cgetopt, gm2-libs/UnixArgs, Base libraries
@subsection gm2-libs/cbuiltin

@example
DEFINITION MODULE FOR "C" cbuiltin ;

FROM SYSTEM IMPORT ADDRESS ;
EXPORT UNQUALIFIED alloca, memcpy,
		   isfinite, isfinitef, isfinitel,
		   isinf_sign, isinf_signf, isinf_signl,
                   sinf, sinl, sin,
                   cosf, cosl, cos,
                   atan2f, atan2l, atan2,
                   sqrtf, sqrtl, sqrt,
                   fabsf, fabsl, fabs,
                   logf, logl, log,
                   expf, expl, exp,
                   log10f, log10l, log10,
                   exp10f, exp10l, exp10,
                   ilogbf, ilogbl, ilogb,
                   significand, significandf, significandl,
                   modf, modff, modfl,
                   nextafter, nextafterf, nextafterl,
                   nexttoward, nexttowardf, nexttowardl,
                   scalb, scalbf, scalbl,
                   scalbn, scalbnf, scalbnl,
                   scalbln, scalblnf, scalblnl,

                   cabsf, cabsl, cabs,
                   cargf, carg, cargl,
                   conjf, conj, conjl,
                   cpowf, cpow, cpowl,
                   csqrtf, csqrt, csqrtl,
                   cexpf, cexp, cexpl,
                   clogf, clog, clogl,
                   csinf, csin, csinl,
                   ccosf, ccos, ccosl,
                   ctanf, ctan, ctanl,
                   casinf, casin, casinl,
                   cacosf, cacos, cacosl,
                   catanf, catan, catanl,

                   index, rindex,
                   memcmp, memset, memmove,
                   strcat, strncat, strcpy, strncpy, strcmp, strncmp,
                   strlen, strstr, strpbrk, strspn, strcspn, strchr, strrchr ;

@findex alloca
PROCEDURE alloca (i: CARDINAL) : ADDRESS ;
@findex memcpy
PROCEDURE memcpy (dest, src: ADDRESS; n: CARDINAL) : ADDRESS ;
@findex isfinite
PROCEDURE isfinite (x: REAL) : BOOLEAN ;
@findex isfinitel
PROCEDURE isfinitel (x: LONGREAL) : BOOLEAN ;
@findex isfinitef
PROCEDURE isfinitef (x: SHORTREAL) : BOOLEAN ;
@findex isinf_sign
PROCEDURE isinf_sign (x: REAL) : BOOLEAN ;
@findex isinf_signl
PROCEDURE isinf_signl (x: LONGREAL) : BOOLEAN ;
@findex isinf_signf
PROCEDURE isinf_signf (x: SHORTREAL) : BOOLEAN ;
@findex sinf
PROCEDURE sinf (x: SHORTREAL) : SHORTREAL ;
@findex sin
PROCEDURE sin (x: REAL) : REAL ;
@findex sinl
PROCEDURE sinl (x: LONGREAL) : LONGREAL ;
@findex cosf
PROCEDURE cosf (x: SHORTREAL) : SHORTREAL ;
@findex cos
PROCEDURE cos (x: REAL) : REAL ;
@findex cosl
PROCEDURE cosl (x: LONGREAL) : LONGREAL ;
@findex atan2f
PROCEDURE atan2f (x, y: SHORTREAL) : SHORTREAL ;
@findex atan2
PROCEDURE atan2 (x, y: REAL) : REAL ;
@findex atan2l
PROCEDURE atan2l (x, y: LONGREAL) : LONGREAL ;
@findex sqrtf
PROCEDURE sqrtf (x: SHORTREAL) : SHORTREAL ;
@findex sqrt
PROCEDURE sqrt (x: REAL) : REAL ;
@findex sqrtl
PROCEDURE sqrtl (x: LONGREAL) : LONGREAL ;
@findex fabsf
PROCEDURE fabsf (x: SHORTREAL) : SHORTREAL ;
@findex fabs
PROCEDURE fabs (x: REAL) : REAL ;
@findex fabsl
PROCEDURE fabsl (x: LONGREAL) : LONGREAL ;
@findex logf
PROCEDURE logf (x: SHORTREAL) : SHORTREAL ;
@findex log
PROCEDURE log (x: REAL) : REAL ;
@findex logl
PROCEDURE logl (x: LONGREAL) : LONGREAL ;
@findex expf
PROCEDURE expf (x: SHORTREAL) : SHORTREAL ;
@findex exp
PROCEDURE exp (x: REAL) : REAL ;
@findex expl
PROCEDURE expl (x: LONGREAL) : LONGREAL ;
@findex log10f
PROCEDURE log10f (x: SHORTREAL) : SHORTREAL ;
@findex log10
PROCEDURE log10 (x: REAL) : REAL ;
@findex log10l
PROCEDURE log10l (x: LONGREAL) : LONGREAL ;
@findex exp10f
PROCEDURE exp10f (x: SHORTREAL) : SHORTREAL ;
@findex exp10
PROCEDURE exp10 (x: REAL) : REAL ;
@findex exp10l
PROCEDURE exp10l (x: LONGREAL) : LONGREAL ;
@findex ilogbf
PROCEDURE ilogbf (x: SHORTREAL) : INTEGER ;
@findex ilogb
PROCEDURE ilogb (x: REAL) : INTEGER ;
@findex ilogbl
PROCEDURE ilogbl (x: LONGREAL) : INTEGER ;

@findex significand
PROCEDURE significand (r: REAL) : REAL ;
@findex significandf
PROCEDURE significandf (s: SHORTREAL) : SHORTREAL ;
@findex significandl
PROCEDURE significandl (l: LONGREAL) : LONGREAL ;

@findex modf
PROCEDURE modf (x: REAL; VAR y: REAL) : REAL ;
@findex modff
PROCEDURE modff (x: SHORTREAL; VAR y: SHORTREAL) : SHORTREAL ;
@findex modfl
PROCEDURE modfl (x: LONGREAL; VAR y: LONGREAL) : LONGREAL ;

@findex nextafter
PROCEDURE nextafter (x, y: REAL) : REAL ;
@findex nextafterf
PROCEDURE nextafterf (x, y: SHORTREAL) : SHORTREAL ;
@findex nextafterl
PROCEDURE nextafterl (x, y: LONGREAL) : LONGREAL ;

@findex nexttoward
PROCEDURE nexttoward (x, y: REAL) : REAL ;
@findex nexttowardf
PROCEDURE nexttowardf (x, y: SHORTREAL) : SHORTREAL ;
@findex nexttowardl
PROCEDURE nexttowardl (x, y: LONGREAL) : LONGREAL ;

@findex scalb
PROCEDURE scalb (x, n: REAL) : REAL ;
@findex scalbf
PROCEDURE scalbf (x, n: SHORTREAL) : SHORTREAL ;
@findex scalbl
PROCEDURE scalbl (x, n: LONGREAL) : LONGREAL ;

@findex scalbn
PROCEDURE scalbn (x: REAL; n: INTEGER) : REAL ;
@findex scalbnf
PROCEDURE scalbnf (x: SHORTREAL; n: INTEGER) : SHORTREAL ;
@findex scalbnl
PROCEDURE scalbnl (x: LONGREAL; n: INTEGER) : LONGREAL ;

@findex scalbln
PROCEDURE scalbln (x: REAL; n: LONGINT) : REAL ;
@findex scalblnf
PROCEDURE scalblnf (x: SHORTREAL; n: LONGINT) : SHORTREAL ;
@findex scalblnl
PROCEDURE scalblnl (x: LONGREAL; n: LONGINT) : LONGREAL ;

@findex cabsf
PROCEDURE cabsf (z: SHORTCOMPLEX) : SHORTREAL ;
@findex cabs
PROCEDURE cabs (z: COMPLEX) : REAL ;
@findex cabsl
PROCEDURE cabsl (z: LONGCOMPLEX) : LONGREAL ;

@findex cargf
PROCEDURE cargf (z: SHORTCOMPLEX) : SHORTREAL ;
@findex carg
PROCEDURE carg (z: COMPLEX) : REAL ;
@findex cargl
PROCEDURE cargl (z: LONGCOMPLEX) : LONGREAL ;

@findex conjf
PROCEDURE conjf (z: SHORTCOMPLEX) : SHORTCOMPLEX ;
@findex conj
PROCEDURE conj (z: COMPLEX) : COMPLEX ;
@findex conjl
PROCEDURE conjl (z: LONGCOMPLEX) : LONGCOMPLEX ;

@findex cpowf
PROCEDURE cpowf (base: SHORTCOMPLEX; exp: SHORTREAL) : SHORTCOMPLEX ;
@findex cpow
PROCEDURE cpow (base: COMPLEX; exp: REAL) : COMPLEX ;
@findex cpowl
PROCEDURE cpowl (base: LONGCOMPLEX; exp: LONGREAL) : LONGCOMPLEX ;

@findex csqrtf
PROCEDURE csqrtf (z: SHORTCOMPLEX) : SHORTCOMPLEX ;
@findex csqrt
PROCEDURE csqrt (z: COMPLEX) : COMPLEX ;
@findex csqrtl
PROCEDURE csqrtl (z: LONGCOMPLEX) : LONGCOMPLEX ;

@findex cexpf
PROCEDURE cexpf (z: SHORTCOMPLEX) : SHORTCOMPLEX ;
@findex cexp
PROCEDURE cexp (z: COMPLEX) : COMPLEX ;
@findex cexpl
PROCEDURE cexpl (z: LONGCOMPLEX) : LONGCOMPLEX ;

@findex clogf
PROCEDURE clogf (z: SHORTCOMPLEX) : SHORTCOMPLEX ;
@findex clog
PROCEDURE clog (z: COMPLEX) : COMPLEX ;
@findex clogl
PROCEDURE clogl (z: LONGCOMPLEX) : LONGCOMPLEX ;

@findex csinf
PROCEDURE csinf (z: SHORTCOMPLEX) : SHORTCOMPLEX ;
@findex csin
PROCEDURE csin (z: COMPLEX) : COMPLEX ;
@findex csinl
PROCEDURE csinl (z: LONGCOMPLEX) : LONGCOMPLEX ;

@findex ccosf
PROCEDURE ccosf (z: SHORTCOMPLEX) : SHORTCOMPLEX ;
@findex ccos
PROCEDURE ccos (z: COMPLEX) : COMPLEX ;
@findex ccosl
PROCEDURE ccosl (z: LONGCOMPLEX) : LONGCOMPLEX ;

@findex ctanf
PROCEDURE ctanf (z: SHORTCOMPLEX) : SHORTCOMPLEX ;
@findex ctan
PROCEDURE ctan (z: COMPLEX) : COMPLEX ;
@findex ctanl
PROCEDURE ctanl (z: LONGCOMPLEX) : LONGCOMPLEX ;

@findex casinf
PROCEDURE casinf (z: SHORTCOMPLEX) : SHORTCOMPLEX ;
@findex casin
PROCEDURE casin (z: COMPLEX) : COMPLEX ;
@findex casinl
PROCEDURE casinl (z: LONGCOMPLEX) : LONGCOMPLEX ;

@findex cacosf
PROCEDURE cacosf (z: SHORTCOMPLEX) : SHORTCOMPLEX ;
@findex cacos
PROCEDURE cacos (z: COMPLEX) : COMPLEX ;
@findex cacosl
PROCEDURE cacosl (z: LONGCOMPLEX) : LONGCOMPLEX ;

@findex catanf
PROCEDURE catanf (z: SHORTCOMPLEX) : SHORTCOMPLEX ;
@findex catan
PROCEDURE catan (z: COMPLEX) : COMPLEX ;
@findex catanl
PROCEDURE catanl (z: LONGCOMPLEX) : LONGCOMPLEX ;

@findex index
PROCEDURE index (s: ADDRESS; c: INTEGER) : ADDRESS ;
@findex rindex
PROCEDURE rindex (s: ADDRESS; c: INTEGER) : ADDRESS ;
@findex memcmp
PROCEDURE memcmp (s1, s2: ADDRESS; n: CARDINAL) : INTEGER ;
@findex memmove
PROCEDURE memmove (s1, s2: ADDRESS; n: CARDINAL) : ADDRESS ;
@findex memset
PROCEDURE memset (s: ADDRESS; c: INTEGER; n: CARDINAL) : ADDRESS ;
@findex strcat
PROCEDURE strcat (dest, src: ADDRESS) : ADDRESS ;
@findex strncat
PROCEDURE strncat (dest, src: ADDRESS; n: CARDINAL) : ADDRESS ;
@findex strcpy
PROCEDURE strcpy (dest, src: ADDRESS) : ADDRESS ;
@findex strncpy
PROCEDURE strncpy (dest, src: ADDRESS; n: CARDINAL) : ADDRESS ;
@findex strcmp
PROCEDURE strcmp (s1, s2: ADDRESS) : INTEGER ;
@findex strncmp
PROCEDURE strncmp (s1, s2: ADDRESS; n: CARDINAL) : INTEGER ;
@findex strlen
PROCEDURE strlen (s: ADDRESS) : INTEGER ;
@findex strstr
PROCEDURE strstr (haystack, needle: ADDRESS) : ADDRESS ;
@findex strpbrk
PROCEDURE strpbrk (s, accept: ADDRESS) : ADDRESS ;
@findex strspn
PROCEDURE strspn (s, accept: ADDRESS) : CARDINAL ;
@findex strcspn
PROCEDURE strcspn (s, accept: ADDRESS) : CARDINAL ;
@findex strchr
PROCEDURE strchr (s: ADDRESS; c: INTEGER) : ADDRESS ;
@findex strrchr
PROCEDURE strrchr (s: ADDRESS; c: INTEGER) : ADDRESS ;

END cbuiltin.
@end example
@page

@node gm2-libs/cgetopt, gm2-libs/cxxabi, gm2-libs/cbuiltin, Base libraries
@subsection gm2-libs/cgetopt

@example
DEFINITION MODULE cgetopt ;

FROM SYSTEM IMPORT ADDRESS ;


TYPE
@findex Options (type)
   Options = ADDRESS ;

VAR
@findex optarg (var)
   optarg                : ADDRESS ;
@findex optind (var)
@findex opterr (var)
@findex optopt (var)
   optind, opterr, optopt: INTEGER ;


(*
   getopt - the getopt() function parses the command-line arguments.
            Its arguments argc and argv are the argument count and array as
            passed to the main() function on program invocation.  An element of
            argv that starts with '-' (and is not exactly "-" or "--") is an
            option element.  The characters of this element (aside from the
            initial '-') are option characters.  If getopt() is called
            repeatedly, it returns successively each of the option characters
            from each of the option elements.
*)

@findex getopt
PROCEDURE getopt (argc: INTEGER; argv: ADDRESS; optstring: ADDRESS) : CHAR ;


(*
   getopt_long - works like getopt() except that it also accepts long options,
                 started with two dashes.  (If the program accepts only long
                 options, then optstring should be specified as an empty string (""),
                 not NULL.)  Long option names may be abbreviated if the abbreviation
                 is unique or is an exact match for some defined option.  A
                 long option may take a parameter, of the form --arg=param or
                 --arg param.
*)

@findex getopt_long
PROCEDURE getopt_long (argc: INTEGER; argv: ADDRESS; optstring: ADDRESS;
                       longopts: ADDRESS; VAR longindex: INTEGER) : INTEGER ;


(*
   getopt_long_only - a wrapper for the C getopt_long_only.
*)

@findex getopt_long_only
PROCEDURE getopt_long_only (argc: INTEGER; argv: ADDRESS; optstring: ADDRESS;
                            longopts: ADDRESS; VAR longindex: INTEGER) : INTEGER ;


(*
   InitOptions - constructor for empty Options.
*)

@findex InitOptions
PROCEDURE InitOptions () : Options ;


(*
   KillOptions - deconstructor for empty Options.
*)

@findex KillOptions
PROCEDURE KillOptions (o: Options) : Options ;


(*
   SetOption - set option[index] with @{name, has_arg, flag, val@}.
*)

@findex SetOption
PROCEDURE SetOption (o: Options; index: CARDINAL;
                     name: ADDRESS; has_arg: BOOLEAN;
                     VAR flag: INTEGER; val: INTEGER) ;


(*
   GetLongOptionArray - return a pointer to the C array containing all
                        long options.
*)

@findex GetLongOptionArray
PROCEDURE GetLongOptionArray (o: Options) : ADDRESS ;


END cgetopt.
@end example
@page

@node gm2-libs/cxxabi, gm2-libs/dtoa, gm2-libs/cgetopt, Base libraries
@subsection gm2-libs/cxxabi

@example
DEFINITION MODULE FOR "C" cxxabi ;

(* This should only be used by the compiler and it matches the
    g++ implementation.  *)

FROM SYSTEM IMPORT ADDRESS ;
EXPORT UNQUALIFIED __cxa_begin_catch, __cxa_end_catch, __cxa_rethrow ;


@findex __cxa_begin_catch
PROCEDURE __cxa_begin_catch (a: ADDRESS) : ADDRESS ;
@findex __cxa_end_catch
PROCEDURE __cxa_end_catch ;
@findex __cxa_rethrow
PROCEDURE __cxa_rethrow ;


END cxxabi.
@end example
@page

@node gm2-libs/dtoa, gm2-libs/errno, gm2-libs/cxxabi, Base libraries
@subsection gm2-libs/dtoa

@example
DEFINITION MODULE dtoa ;

FROM SYSTEM IMPORT ADDRESS ;

TYPE
@findex Mode (type)
   Mode = (maxsignificant, decimaldigits) ;


(*
   strtod - returns a REAL given a string, s.  It will set
            error to TRUE if the number is too large.
*)

@findex strtod
PROCEDURE strtod (s: ADDRESS; VAR error: BOOLEAN) : REAL ;


(*
   dtoa - converts a REAL, d, into a string.  The address of the
          string is returned.
          mode       indicates the type of conversion required.
          ndigits    determines the number of digits according to mode.
          decpt      the position of the decimal point.
          sign       does the string have a sign?
*)

@findex dtoa
PROCEDURE dtoa (d        : REAL;
                mode     : Mode;
                ndigits  : INTEGER;
	        VAR decpt: INTEGER;
	        VAR sign : BOOLEAN) : ADDRESS ;


END dtoa.
@end example
@page

@node gm2-libs/errno, gm2-libs/gdbif, gm2-libs/dtoa, Base libraries
@subsection gm2-libs/errno

@example
DEFINITION MODULE errno ;

CONST
    EINTR  =  4 ;   (* system call interrupted *)
    ERANGE = 34 ;   (* result is too large     *)
    EAGAIN = 11 ;   (* retry the system call   *)

@findex geterrno
PROCEDURE geterrno () : INTEGER ;


END errno.
@end example
@page

@node gm2-libs/gdbif, gm2-libs/ldtoa, gm2-libs/errno, Base libraries
@subsection gm2-libs/gdbif

@example
DEFINITION MODULE gdbif ;

(*  Provides interactive connectivity with gdb useful for debugging
    Modula-2 shared libraries.  *)

EXPORT UNQUALIFIED sleepSpin, finishSpin, connectSpin ;


(*
   finishSpin - sets boolean mustWait to FALSE.
*)

@findex finishSpin
PROCEDURE finishSpin ;


(*
   sleepSpin - waits for the boolean variable mustWait to become FALSE.
               It sleeps for a second between each test of the variable.
*)

@findex sleepSpin
PROCEDURE sleepSpin ;


(*
   connectSpin - breakpoint placeholder.  Its only purpose is to allow users
                 to set a breakpoint.  This procedure is called once
                 sleepSpin is released from its spin (via a call from
                 finishSpin).
*)

@findex connectSpin
PROCEDURE connectSpin ;


END gdbif.
@end example
@page

@node gm2-libs/ldtoa, gm2-libs/libc, gm2-libs/gdbif, Base libraries
@subsection gm2-libs/ldtoa

@example
DEFINITION MODULE ldtoa ;

FROM SYSTEM IMPORT ADDRESS ;

TYPE
@findex Mode (type)
   Mode = (maxsignificant, decimaldigits) ;


(*
   strtold - returns a LONGREAL given a C string, s.  It will set
             error to TRUE if the number is too large or badly formed.
*)

@findex strtold
PROCEDURE strtold (s: ADDRESS; VAR error: BOOLEAN) : LONGREAL ;


(*
   ldtoa - converts a LONGREAL, d, into a string.  The address of the
           string is returned.
           mode       indicates the type of conversion required.
           ndigits    determines the number of digits according to mode.
           decpt      the position of the decimal point.
           sign       does the string have a sign?
*)

@findex ldtoa
PROCEDURE ldtoa (d        : LONGREAL;
                 mode     : Mode;
                 ndigits  : INTEGER;
                 VAR decpt: INTEGER;
                 VAR sign : BOOLEAN) : ADDRESS ;


END ldtoa.
@end example
@page

@node gm2-libs/libc, gm2-libs/libm, gm2-libs/ldtoa, Base libraries
@subsection gm2-libs/libc

@example
DEFINITION MODULE FOR "C" libc ;

FROM SYSTEM IMPORT ADDRESS, CSIZE_T, CSSIZE_T ;

EXPORT UNQUALIFIED time_t, timeb, tm, ptrToTM,
                   write, read,
                   system, abort,
                   malloc, free,
                   exit, isatty,
                   getenv, putenv, getpid,
                   dup, close, open, lseek,
                   readv, writev,
                   perror, creat,
                   getcwd, chown, strlen, strcpy, strncpy,
                   unlink, setenv,
                   memcpy, memset, memmove, printf, realloc,
                   rand, srand,
                   time, localtime, ftime,
                   shutdown, rename, setjmp, longjmp, atexit,
                   ttyname, sleep, execv ;


TYPE
@findex time_t (type)
   time_t = LONGINT ;

@findex ptrToTM (type)
   ptrToTM = POINTER TO tm ;
@findex tm (type)
   tm = RECORD
           tm_sec: INTEGER ;     (* Seconds.     [0-60] (1 leap second) *)
           tm_min: INTEGER ;     (* Minutes.     [0-59]   *)
           tm_hour: INTEGER ;    (* Hours.       [0-23]   *)
           tm_mday: INTEGER ;    (* Day.         [1-31]   *)
           tm_mon: INTEGER ;     (* Month.       [0-11]   *)
           tm_year: INTEGER ;    (* Year - 1900.          *)
           tm_wday: INTEGER ;    (* Day of week. [0-6]    *)
           tm_yday: INTEGER ;    (* Days in year.[0-365]  *)
           tm_isdst: INTEGER ;   (* DST.         [-1/0/1] *)
           tm_gmtoff: LONGINT ;  (* Seconds east of UTC.  *)
           tm_zone: ADDRESS ;    (* char * zone name      *)
@findex END (type)
        END ;

@findex timeb (type)
   timeb = RECORD
              time    : time_t ;
              millitm : SHORTCARD ;
              timezone: SHORTCARD ;
              dstflag : SHORTCARD ;
@findex END (type)
           END ;

@findex exitP (type)
   exitP = PROCEDURE () : INTEGER ;


(*
     ssize_t write (int d, void *buf, size_t nbytes)
*)

@findex write
PROCEDURE write (d: INTEGER; buf: ADDRESS; nbytes: CSIZE_T) : [ CSSIZE_T ] ;


(*
     ssize_t read (int d, void *buf, size_t nbytes)
*)

@findex read
PROCEDURE read (d: INTEGER; buf: ADDRESS; nbytes: CSIZE_T) : [ CSSIZE_T ] ;


(*
     int system(string)
     char *string;
*)

@findex system
PROCEDURE system (a: ADDRESS) : [ INTEGER ] ;


(*
     abort - generate a fault

     abort() first closes all open files if possible, then sends
     an IOT signal to the process.  This signal usually results
     in termination with a core dump, which may be used for
     debugging.

     It is possible for abort() to return control if is caught or
     ignored, in which case the value returned is that of the
     kill(2V) system call.
*)

@findex abort
PROCEDURE abort <* noreturn *> ;


(*
     malloc - memory allocator.

     void *malloc(size_t size);

     malloc() returns a pointer to a block of at least size
     bytes, which is appropriately aligned.  If size is zero,
     malloc() returns a non-NULL pointer, but this pointer should
     not be dereferenced.
*)

@findex malloc
PROCEDURE malloc (size: CSIZE_T) : ADDRESS ;


(*
     free - memory deallocator.

     free (void *ptr);

     free() releases a previously allocated block.  Its argument
     is a pointer to a block previously allocated by malloc,
     calloc, realloc, malloc, or memalign.
*)

@findex free
PROCEDURE free (ptr: ADDRESS) ;


(*
     void *realloc (void *ptr, size_t size);

     realloc changes the size of the memory block pointed to
     by ptr to size bytes. The contents will be  unchanged  to
     the minimum of the old and new sizes; newly allocated memory
     will be uninitialized. If ptr is NIL, the call is
     equivalent  to malloc(size); if size is equal to zero, the
     call is equivalent to free(ptr). Unless ptr is NIL, it
     must have been returned by an earlier call to malloc(),
     realloc.
*)

@findex realloc
PROCEDURE realloc (ptr: ADDRESS; size: CSIZE_T) : ADDRESS ;


(*
   isatty - does this descriptor refer to a terminal.
*)

@findex isatty
PROCEDURE isatty (fd: INTEGER) : INTEGER ;


(*
   exit - returns control to the invoking process. Result, r, is
          returned.
*)

@findex exit
PROCEDURE exit (r: INTEGER) <* noreturn *> ;


(*
   getenv - returns the C string for the equivalent C environment
            variable.
*)

@findex getenv
PROCEDURE getenv (s: ADDRESS) : ADDRESS ;


(*
   putenv - change or add an environment variable.
*)

@findex putenv
PROCEDURE putenv (s: ADDRESS) : INTEGER ;


(*
   getpid - returns the UNIX process identification number.
*)

@findex getpid
PROCEDURE getpid () : INTEGER ;


(*
   dup - duplicates the file descriptor, d.
*)

@findex dup
PROCEDURE dup (d: INTEGER) : INTEGER ;


(*
   close - closes the file descriptor, d.
*)

@findex close
PROCEDURE close (d: INTEGER) : [ INTEGER ] ;


(*
   open - open the file, filename with flag and mode.
*)

@findex open
PROCEDURE open (filename: ADDRESS; oflag: INTEGER; ...) : INTEGER ;


(*
   creat - creates a new file
*)

@findex creat
PROCEDURE creat (filename: ADDRESS; mode: CARDINAL) : INTEGER;


(*
   lseek - calls unix lseek:

           off_t lseek(int fildes, off_t offset, int whence);
*)

@findex lseek
PROCEDURE lseek (fd: INTEGER; offset: LONGINT; whence: INTEGER) : LONGINT ;


(*
   perror - writes errno and string. (ARRAY OF CHAR is translated onto ADDRESS).
*)

@findex perror
PROCEDURE perror (string: ARRAY OF CHAR);


(*
   readv - reads an io vector of bytes.
*)

@findex readv
PROCEDURE readv (fd: INTEGER; v: ADDRESS; n: INTEGER) : [ INTEGER ] ;


(*
   writev - writes an io vector of bytes.
*)

@findex writev
PROCEDURE writev (fd: INTEGER; v: ADDRESS; n: INTEGER) : [ INTEGER ] ;


(*
   getcwd - copies the absolute pathname of the
            current working directory to the array pointed to by buf,
            which is of length size.

            If the current absolute path name would require a buffer
            longer than size elements, NULL is returned, and errno is
            set to ERANGE; an application should check for this error,
            and allocate a larger buffer if necessary.
*)

@findex getcwd
PROCEDURE getcwd (buf: ADDRESS; size: CSIZE_T) : ADDRESS ;


(*
   chown - The  owner  of  the  file  specified  by  path or by fd is
           changed.  Only the super-user may change the  owner  of  a
           file.   The  owner  of  a file may change the group of the
           file to any group of which that owner is  a  member.   The
           super-user may change the group arbitrarily.

           If  the owner or group is specified as -1, then that ID is
           not changed.

           On success, zero is returned.  On error, -1  is  returned,
           and errno is set appropriately.
*)

@findex chown
PROCEDURE chown (filename: ADDRESS; uid, gid: INTEGER) : [ INTEGER ] ;


(*
   strlen - returns the length of string, a.
*)

@findex strlen
PROCEDURE strlen (a: ADDRESS) : CSIZE_T ;


(*
   strcpy - copies string, src, into, dest.
            It returns dest.
*)

@findex strcpy
PROCEDURE strcpy (dest, src: ADDRESS) : [ ADDRESS ] ;


(*
   strncpy - copies string, src, into, dest, copying at most, n, bytes.
             It returns dest.
*)

@findex strncpy
PROCEDURE strncpy (dest, src: ADDRESS; n: CARDINAL) : [ ADDRESS ] ;


(*
   unlink - removes file and returns 0 if successful.
*)

@findex unlink
PROCEDURE unlink (file: ADDRESS) : [ INTEGER ] ;


(*
   memcpy - copy memory area

   SYNOPSIS

   #include <string.h>

   void *memcpy(void *dest, const void *src, size_t n);
   It returns dest.
*)

@findex memcpy
PROCEDURE memcpy (dest, src: ADDRESS; size: CSIZE_T) : [ ADDRESS ] ;


(*
   memset - fill memory with a constant byte

   SYNOPSIS

   #include <string.h>

   void *memset(void *s, int c, size_t n);
   It returns s.
*)

@findex memset
PROCEDURE memset (s: ADDRESS; c: INTEGER; size: CSIZE_T) : [ ADDRESS ] ;


(*
   memmove - copy memory areas which may overlap

   SYNOPSIS

   #include <string.h>

   void *memmove(void *dest, const void *src, size_t n);
   It returns dest.
*)

@findex memmove
PROCEDURE memmove (dest, src: ADDRESS; size: CSIZE_T) : [ ADDRESS ] ;


(*
   int printf(const char *format, ...);
*)

@findex printf
PROCEDURE printf (format: ARRAY OF CHAR; ...) : [ INTEGER ] ;


(*
   setenv - sets environment variable, name, to value.
            It will overwrite an existing value if, overwrite,
            is true.  It returns 0 on success and -1 for an error.
*)

@findex setenv
PROCEDURE setenv (name: ADDRESS; value: ADDRESS; overwrite: INTEGER) : [ INTEGER ] ;


(*
   srand - initialize the random number seed.
*)

@findex srand
PROCEDURE srand (seed: INTEGER) ;


(*
   rand - return a random integer.
*)

@findex rand
PROCEDURE rand () : INTEGER ;


(*
   time - returns a pointer to the time_t value. If, a,
          is not NIL then the libc value is copied into
          memory at address, a.
*)

@findex time
PROCEDURE time (a: ADDRESS) : time_t ;


(*
   localtime - returns a pointer to the libc copy of the tm
               structure.
*)

@findex localtime
PROCEDURE localtime (VAR t: time_t) : ADDRESS ;


(*
   ftime - return date and time.
*)

@findex ftime
PROCEDURE ftime (VAR t: timeb) : [ INTEGER ] ;


(*
   shutdown - shutdown a socket, s.
              if how = 0, then no more reads are allowed.
              if how = 1, then no more writes are allowed.
              if how = 2, then mo more reads or writes are allowed.
*)

@findex shutdown
PROCEDURE shutdown (s: INTEGER; how: INTEGER) : [ INTEGER ] ;


(*
   rename - change the name or location of a file
*)

@findex rename
PROCEDURE rename (oldpath, newpath: ADDRESS) : [ INTEGER ] ;


(*
   setjmp - returns 0 if returning directly, and non-zero
            when returning from longjmp using the saved
            context.
*)

@findex setjmp
PROCEDURE setjmp (env: ADDRESS) : INTEGER ;


(*
   longjmp - restores the environment saved by the last call
             of setjmp with the corresponding env argument.
             After longjmp is completed, program execution
             continues as if the corresponding call of setjmp
             had just returned the value val.  The value of
             val must not be zero.
*)

@findex longjmp
PROCEDURE longjmp (env: ADDRESS; val: INTEGER) ;


(*
   atexit - execute, proc, when the function exit is called.
*)

@findex atexit
PROCEDURE atexit (proc: exitP) : [ INTEGER ] ;


(*
   ttyname - returns a pointer to a string determining the ttyname.
*)

@findex ttyname
PROCEDURE ttyname (filedes: INTEGER) : ADDRESS ;


(*
   sleep - calling thread sleeps for seconds.
*)

@findex sleep
PROCEDURE sleep (seconds: CARDINAL) : [ CARDINAL ] ;


(*
   execv - execute a file.
*)

@findex execv
PROCEDURE execv (pathname: ADDRESS; argv: ADDRESS) : [ INTEGER ] ;


END libc.
@end example
@page

@node gm2-libs/libm, gm2-libs/sckt, gm2-libs/libc, Base libraries
@subsection gm2-libs/libm

@example
DEFINITION MODULE FOR "C" libm ;

(* Users are strongly advised to use MathLib0 or RealMath as calls
   to functions within these modules will generate inline code.
   This module is used by MathLib0 and RealMath when inline code cannot
   be generated.  *)

EXPORT UNQUALIFIED sin, sinl, sinf,
                   cos, cosl, cosf,
                   tan, tanl, tanf,
                   sqrt, sqrtl, sqrtf,
                   asin, asinl, asinf,
                   acos, acosl, acosf,
                   atan, atanl, atanf,
                   atan2, atan2l, atan2f,
                   exp, expl, expf,
                   log, logl, logf,
                   exp10, exp10l, exp10f,
                   pow, powl, powf,
                   floor, floorl, floorf,
                   ceil, ceill, ceilf ;

@findex sin
PROCEDURE sin (x: REAL) : REAL ;
@findex sinl
PROCEDURE sinl (x: LONGREAL) : LONGREAL ;
@findex sinf
PROCEDURE sinf (x: SHORTREAL) : SHORTREAL ;
@findex cos
PROCEDURE cos (x: REAL) : REAL ;
@findex cosl
PROCEDURE cosl (x: LONGREAL) : LONGREAL ;
@findex cosf
PROCEDURE cosf (x: SHORTREAL) : SHORTREAL ;
@findex tan
PROCEDURE tan (x: REAL) : REAL ;
@findex tanl
PROCEDURE tanl (x: LONGREAL) : LONGREAL ;
@findex tanf
PROCEDURE tanf (x: SHORTREAL) : SHORTREAL ;
@findex sqrt
PROCEDURE sqrt (x: REAL) : REAL ;
@findex sqrtl
PROCEDURE sqrtl (x: LONGREAL) : LONGREAL ;
@findex sqrtf
PROCEDURE sqrtf (x: SHORTREAL) : SHORTREAL ;
@findex asin
PROCEDURE asin (x: REAL) : REAL ;
@findex asinl
PROCEDURE asinl (x: LONGREAL) : LONGREAL ;
@findex asinf
PROCEDURE asinf (x: SHORTREAL) : SHORTREAL ;
@findex acos
PROCEDURE acos (x: REAL) : REAL ;
@findex acosl
PROCEDURE acosl (x: LONGREAL) : LONGREAL ;
@findex acosf
PROCEDURE acosf (x: SHORTREAL) : SHORTREAL ;
@findex atan
PROCEDURE atan (x: REAL) : REAL ;
@findex atanl
PROCEDURE atanl (x: LONGREAL) : LONGREAL ;
@findex atanf
PROCEDURE atanf (x: SHORTREAL) : SHORTREAL ;
@findex atan2
PROCEDURE atan2 (x, y: REAL) : REAL ;
@findex atan2l
PROCEDURE atan2l (x, y: LONGREAL) : LONGREAL ;
@findex atan2f
PROCEDURE atan2f (x, y: SHORTREAL) : SHORTREAL ;
@findex exp
PROCEDURE exp (x: REAL) : REAL ;
@findex expl
PROCEDURE expl (x: LONGREAL) : LONGREAL ;
@findex expf
PROCEDURE expf (x: SHORTREAL) : SHORTREAL ;
@findex log
PROCEDURE log (x: REAL) : REAL ;
@findex logl
PROCEDURE logl (x: LONGREAL) : LONGREAL ;
@findex logf
PROCEDURE logf (x: SHORTREAL) : SHORTREAL ;
@findex exp10
PROCEDURE exp10 (x: REAL) : REAL ;
@findex exp10l
PROCEDURE exp10l (x: LONGREAL) : LONGREAL ;
@findex exp10f
PROCEDURE exp10f (x: SHORTREAL) : SHORTREAL ;
@findex pow
PROCEDURE pow (x, y: REAL) : REAL ;
@findex powl
PROCEDURE powl (x, y: LONGREAL) : LONGREAL ;
@findex powf
PROCEDURE powf (x, y: SHORTREAL) : SHORTREAL ;
@findex floor
PROCEDURE floor (x: REAL) : REAL ;
@findex floorl
PROCEDURE floorl (x: LONGREAL) : LONGREAL ;
@findex floorf
PROCEDURE floorf (x: SHORTREAL) : SHORTREAL ;
@findex ceil
PROCEDURE ceil (x: REAL) : REAL ;
@findex ceill
PROCEDURE ceill (x: LONGREAL) : LONGREAL ;
@findex ceilf
PROCEDURE ceilf (x: SHORTREAL) : SHORTREAL ;

END libm.
@end example
@page

@node gm2-libs/sckt, gm2-libs/termios, gm2-libs/libm, Base libraries
@subsection gm2-libs/sckt

@example
DEFINITION MODULE sckt ;

FROM SYSTEM IMPORT ADDRESS ;
EXPORT UNQUALIFIED tcpServerState,
                   tcpServerEstablish, tcpServerEstablishPort,
                   tcpServerAccept, getLocalIP,
                   tcpServerPortNo, tcpServerIP, tcpServerSocketFd,
                   tcpServerClientIP, tcpServerClientPortNo,
                   tcpClientState,
                   tcpClientSocket, tcpClientSocketIP, tcpClientConnect,
                   tcpClientPortNo, tcpClientIP, tcpClientSocketFd ;

TYPE
@findex tcpServerState (type)
   tcpServerState = ADDRESS ;
@findex tcpClientState (type)
   tcpClientState = ADDRESS ;


(*
   tcpServerEstablish - returns a tcpState containing the relevant
                        information about a socket declared to receive
                        tcp connections.
*)

@findex tcpServerEstablish
PROCEDURE tcpServerEstablish () : tcpServerState ;


(*
   tcpServerEstablishPort - returns a tcpState containing the relevant
                            information about a socket declared to receive
                            tcp connections.  This method attempts to use
                            the port specified by the parameter.
*)

@findex tcpServerEstablishPort
PROCEDURE tcpServerEstablishPort (port: CARDINAL) : tcpServerState ;


(*
   tcpServerAccept - returns a file descriptor once a client has connected and
                     been accepted.
*)

@findex tcpServerAccept
PROCEDURE tcpServerAccept (s: tcpServerState) : INTEGER ;


(*
   tcpServerPortNo - returns the portNo from structure, s.
*)

@findex tcpServerPortNo
PROCEDURE tcpServerPortNo (s: tcpServerState) : CARDINAL ;


(*
   tcpSocketFd - returns the sockFd from structure, s.
*)

@findex tcpServerSocketFd
PROCEDURE tcpServerSocketFd (s: tcpServerState) : INTEGER ;


(*
   getLocalIP - returns the IP address of this machine.
*)

@findex getLocalIP
PROCEDURE getLocalIP (s: tcpServerState) : CARDINAL ;


(*
   tcpServerIP - returns the IP address from structure, s.
*)

@findex tcpServerIP
PROCEDURE tcpServerIP (s: tcpServerState) : CARDINAL ;


(*
   tcpServerClientIP - returns the IP address of the client who
                       has connected to server, s.
*)

@findex tcpServerClientIP
PROCEDURE tcpServerClientIP (s: tcpServerState) : CARDINAL ;


(*
   tcpServerClientPortNo - returns the port number of the client who
                           has connected to server, s.
*)

@findex tcpServerClientPortNo
PROCEDURE tcpServerClientPortNo (s: tcpServerState) : CARDINAL ;


(*
   tcpClientSocket - returns a file descriptor (socket) which has
                     connected to, serverName:portNo.
*)

@findex tcpClientSocket
PROCEDURE tcpClientSocket (serverName: ADDRESS; portNo: CARDINAL) : tcpClientState ;


(*
   tcpClientSocketIP - returns a file descriptor (socket) which has
                       connected to, ip:portNo.
*)

@findex tcpClientSocketIP
PROCEDURE tcpClientSocketIP (ip: CARDINAL; portNo: CARDINAL) : tcpClientState ;


(*
   tcpClientConnect - returns the file descriptor associated with, s,
                      once a connect has been performed.
*)

@findex tcpClientConnect
PROCEDURE tcpClientConnect (s: tcpClientState) : INTEGER ;


(*
   tcpClientPortNo - returns the portNo from structure, s.
*)

@findex tcpClientPortNo
PROCEDURE tcpClientPortNo (s: tcpClientState) : INTEGER ;


(*
   tcpClientSocketFd - returns the sockFd from structure, s.
*)

@findex tcpClientSocketFd
PROCEDURE tcpClientSocketFd (s: tcpClientState) : INTEGER ;


(*
   tcpClientIP - returns the IP address from structure, s.
*)

@findex tcpClientIP
PROCEDURE tcpClientIP (s: tcpClientState) : CARDINAL ;


END sckt.
@end example
@page

@node gm2-libs/termios, gm2-libs/wrapc, gm2-libs/sckt, Base libraries
@subsection gm2-libs/termios

@example
DEFINITION MODULE termios ;

FROM SYSTEM IMPORT ADDRESS ;

TYPE
@findex TERMIOS (type)
   TERMIOS = ADDRESS ;

@findex ControlChar (type)
   ControlChar = (vintr, vquit, verase, vkill, veof, vtime, vmin,
                  vswtc, vstart, vstop, vsusp, veol, vreprint, vdiscard,
                  vwerase, vlnext, veol2) ;

@findex Flag (type)
   Flag = (
           (* input flag bits *)
           ignbrk, ibrkint, ignpar, iparmrk, inpck, istrip, inlcr,
           igncr, icrnl, iuclc, ixon, ixany, ixoff, imaxbel,
           (* output flag bits *)
           opost, olcuc, onlcr, ocrnl, onocr, onlret, ofill, ofdel,
           onl0, onl1, ocr0, ocr1, ocr2, ocr3,
           otab0, otab1, otab2, otab3, obs0, obs1, off0, off1, ovt0, ovt1,
           (* baud rate *)
           b0, b50, b75, b110, b135, b150, b200, b300, b600, b1200,
           b1800, b2400, b4800, b9600, b19200, b38400,
           b57600, b115200, b240400, b460800, b500000, b576000,
           b921600, b1000000, b1152000, b1500000, b2000000, b2500000,
           b3000000, b3500000, b4000000, maxbaud, crtscts,
           (* character size *)
           cs5, cs6, cs7, cs8, cstopb, cread, parenb, parodd, hupcl, clocal,
           (* local flags *)
           lisig, licanon, lxcase, lecho, lechoe, lechok, lechonl, lnoflsh,
           ltopstop, lechoctl, lechoprt, lechoke, lflusho, lpendin, liexten) ;


(*
   InitTermios - new data structure.
*)

@findex InitTermios
PROCEDURE InitTermios () : TERMIOS ;


(*
   KillTermios - delete data structure.
*)

@findex KillTermios
PROCEDURE KillTermios (t: TERMIOS) : TERMIOS ;


(*
   cfgetospeed - return output baud rate.
*)

@findex cfgetospeed
PROCEDURE cfgetospeed (t: TERMIOS) : INTEGER ;


(*
   cfgetispeed - return input baud rate.
*)

@findex cfgetispeed
PROCEDURE cfgetispeed (t: TERMIOS) : INTEGER ;


(*
   cfsetospeed - set output baud rate.
*)

@findex cfsetospeed
PROCEDURE cfsetospeed (t: TERMIOS; b: CARDINAL) : INTEGER ;


(*
   cfsetispeed - set input baud rate.
*)

@findex cfsetispeed
PROCEDURE cfsetispeed (t: TERMIOS; b: CARDINAL) : INTEGER ;


(*
   cfsetspeed - set input and output baud rate.
*)

@findex cfsetspeed
PROCEDURE cfsetspeed (t: TERMIOS; b: CARDINAL) : INTEGER ;


(*
   tcgetattr - get state of, fd, into, t.
*)

@findex tcgetattr
PROCEDURE tcgetattr (fd: INTEGER; t: TERMIOS) : INTEGER ;


(*
   The following three functions return the different option values.
*)

@findex tcsnow
PROCEDURE tcsnow () : INTEGER ;   (* alter fd now *)
@findex tcsdrain
PROCEDURE tcsdrain () : INTEGER ; (* alter when all output has been sent *)
@findex tcsflush
PROCEDURE tcsflush () : INTEGER ; (* like drain, except discard any pending input *)


(*
   tcsetattr - set state of, fd, to, t, using option.
*)

@findex tcsetattr
PROCEDURE tcsetattr (fd: INTEGER; option: INTEGER; t: TERMIOS) : INTEGER ;


(*
   cfmakeraw - sets, t, to raw mode.
*)

@findex cfmakeraw
PROCEDURE cfmakeraw (t: TERMIOS) ;


(*
   tcsendbreak - send zero bits for duration.
*)

@findex tcsendbreak
PROCEDURE tcsendbreak (fd: INTEGER; duration: INTEGER) : INTEGER ;


(*
   tcdrain - waits for pending output to be written on, fd.
*)

@findex tcdrain
PROCEDURE tcdrain (fd: INTEGER) : INTEGER ;


(*
   tcflushi - flush input.
*)

@findex tcflushi
PROCEDURE tcflushi (fd: INTEGER) : INTEGER ;


(*
   tcflusho - flush output.
*)

@findex tcflusho
PROCEDURE tcflusho (fd: INTEGER) : INTEGER ;


(*
   tcflushio - flush input and output.
*)

@findex tcflushio
PROCEDURE tcflushio (fd: INTEGER) : INTEGER ;


(*
   tcflowoni - restart input on, fd.
*)

@findex tcflowoni
PROCEDURE tcflowoni (fd: INTEGER) : INTEGER ;


(*
   tcflowoffi - stop input on, fd.
*)

@findex tcflowoffi
PROCEDURE tcflowoffi (fd: INTEGER) : INTEGER ;


(*
   tcflowono - restart output on, fd.
*)

@findex tcflowono
PROCEDURE tcflowono (fd: INTEGER) : INTEGER ;


(*
   tcflowoffo - stop output on, fd.
*)

@findex tcflowoffo
PROCEDURE tcflowoffo (fd: INTEGER) : INTEGER ;


(*
   GetFlag - sets a flag value from, t, in, b, and returns TRUE
             if, t, supports, f.
*)

@findex GetFlag
PROCEDURE GetFlag (t: TERMIOS; f: Flag; VAR b: BOOLEAN) : BOOLEAN ;


(*
   SetFlag - sets a flag value in, t, to, b, and returns TRUE if
             this flag value is supported.
*)

@findex SetFlag
PROCEDURE SetFlag (t: TERMIOS; f: Flag; b: BOOLEAN) : BOOLEAN ;


(*
   GetChar - sets a CHAR, ch, value from, t, and returns TRUE if
             this value is supported.
*)

@findex GetChar
PROCEDURE GetChar (t: TERMIOS; c: ControlChar; VAR ch: CHAR) : BOOLEAN ;


(*
   SetChar - sets a CHAR value in, t, and returns TRUE if, c,
             is supported.
*)

@findex SetChar
PROCEDURE SetChar (t: TERMIOS; c: ControlChar; ch: CHAR) : BOOLEAN ;


END termios.
@end example
@page

@node gm2-libs/wrapc, , gm2-libs/termios, Base libraries
@subsection gm2-libs/wrapc

@example
DEFINITION MODULE wrapc ;

FROM SYSTEM IMPORT ADDRESS ;

EXPORT QUALIFIED strtime, filesize, fileinode,
                 getrand, getusername, filemtime,
                 getnameuidgid, signbit, signbitf, signbitl,
		 isfinite, isfinitel, isfinitef ;


(*
   strtime - returns the C string for the equivalent C asctime
             function.
*)

@findex strtime
PROCEDURE strtime () : ADDRESS ;


(*
   filesize - assigns the size of a file, f, into low, high and
              returns zero if successful.
*)

@findex filesize
PROCEDURE filesize (f: INTEGER; VAR low, high: CARDINAL) : INTEGER ;


(*
   fileinode - return the inode associated with file, f.
*)

@findex fileinode
PROCEDURE fileinode (f: INTEGER; VAR low, high: CARDINAL) : INTEGER ;


(*
   filemtime - returns the mtime of a file, f.
*)

@findex filemtime
PROCEDURE filemtime (f: INTEGER) : INTEGER ;


(*
   getrand - returns a random number between 0..n-1
*)

@findex getrand
PROCEDURE getrand (n: INTEGER) : INTEGER ;


(*
   getusername - returns a C string describing the current user.
*)

@findex getusername
PROCEDURE getusername () : ADDRESS ;


(*
   getnameuidgid - fills in the, uid, and, gid, which represents
                   user, name.
*)

@findex getnameuidgid
PROCEDURE getnameuidgid (name: ADDRESS; VAR uid, gid: INTEGER) ;


(*
   in C these procedure functions are really macros, so we provide
   real C functions and let gm2 call these if the builtins
   are unavailable.
*)

@findex signbit
PROCEDURE signbit (r: REAL) : INTEGER ;
@findex signbitf
PROCEDURE signbitf (s: SHORTREAL) : INTEGER ;
@findex signbitl
PROCEDURE signbitl (l: LONGREAL) : INTEGER ;


(*
   isfinite - provide non builtin alternative to the gcc builtin isfinite.
              Returns 1 if x is finite and 0 if it is not.
*)

@findex isfinite
PROCEDURE isfinite (x: REAL) : INTEGER ;


(*
   isfinitef - provide non builtin alternative to the gcc builtin isfinite.
               Returns 1 if x is finite and 0 if it is not.
*)

@findex isfinitef
PROCEDURE isfinitef (x: SHORTREAL) : INTEGER ;


(*
   isfinitel - provide non builtin alternative to the gcc builtin isfinite.
               Returns 1 if x is finite and 0 if it is not.
*)

@findex isfinitel
PROCEDURE isfinitel (x: LONGREAL) : INTEGER ;


END wrapc.
@end example
@page


@c ------------------------------------------------------------
@node PIM and Logitech 3.0 Compatible, PIM coroutine support, Base libraries, Libraries
@section PIM and Logitech 3.0 Compatible

@c README.texi describes the additional PIM libraries.
@c Copyright @copyright{} 2000-2023 Free Software Foundation, Inc.
@c
@c This is part of the GM2 manual.
@c For copying conditions, see the file gcc/doc/include/fdl.texi.

These modules are provided to enable legacy Modula-2 applications to
build with GNU Modula-2. It is advised that these module should not
be used for new projects, maybe the ISO libraries or the native
compiler PIM libraries (FIO) should be used instead.

Here is an outline of the module layering:

@example

InOut  RealInOut  LongIO CardinalIO
    \     |       |      /
           Terminal
-----------------------------------
              |
           Termbase
           /      \
    Keyboard      Display

@end example

Above the line are user level PIM [234] and Logitech 3.0 compatible
modules.  Below the line Logitech 3.0 advised that these modules
should be considered part of the runtime system. The libraries do
not provide all the features found in the Logitech libraries as
a number of these features were MS-DOS related. Essentially the
basic input/output, file system, string manipulation and conversion
routines are provided. Access to DOSCALL, graphics, time and date
are not as these were constrained by the limitations of MS-DOS.

The following libraries are contained within the base GNU Modula-2
libraries and are also Logitech-3.0 compatible: @xref{gm2-libs/ASCII},
@xref{gm2-libs/Storage} and @xref{gm2-libs/MathLib0}.  These libraries
are always available for any dialect of the language (although their
implementation and behaviour might differ, for example Storage ISO and
PIM).

The following libraries are Logitech-3.0 compatible but fall outside
the base GNU Modula-2 libraries.
@menu
* gm2-libs-pim/BitBlockOps::BitBlockOps.def
* gm2-libs-pim/BitByteOps::BitByteOps.def
* gm2-libs-pim/BitWordOps::BitWordOps.def
* gm2-libs-pim/BlockOps::BlockOps.def
* gm2-libs-pim/Break::Break.def
* gm2-libs-pim/CardinalIO::CardinalIO.def
* gm2-libs-pim/Conversions::Conversions.def
* gm2-libs-pim/DebugPMD::DebugPMD.def
* gm2-libs-pim/DebugTrace::DebugTrace.def
* gm2-libs-pim/Delay::Delay.def
* gm2-libs-pim/Display::Display.def
* gm2-libs-pim/ErrorCode::ErrorCode.def
* gm2-libs-pim/FileSystem::FileSystem.def
* gm2-libs-pim/FloatingUtilities::FloatingUtilities.def
* gm2-libs-pim/InOut::InOut.def
* gm2-libs-pim/Keyboard::Keyboard.def
* gm2-libs-pim/LongIO::LongIO.def
* gm2-libs-pim/NumberConversion::NumberConversion.def
* gm2-libs-pim/Random::Random.def
* gm2-libs-pim/RealConversions::RealConversions.def
* gm2-libs-pim/RealInOut::RealInOut.def
* gm2-libs-pim/Strings::Strings.def
* gm2-libs-pim/Termbase::Termbase.def
* gm2-libs-pim/Terminal::Terminal.def
* gm2-libs-pim/TimeDate::TimeDate.def
@end menu

@node gm2-libs-pim/BitBlockOps, gm2-libs-pim/BitByteOps, , PIM and Logitech 3.0 Compatible
@subsection gm2-libs-pim/BitBlockOps

@example
DEFINITION MODULE BitBlockOps ;


FROM SYSTEM IMPORT ADDRESS ;


(*
   BlockAnd - performs a bitwise AND on blocks
              [dest..dest+size-1] := [dest..dest+size-1] AND
                                     [src..src+size-1]
*)

@findex BlockAnd
PROCEDURE BlockAnd (dest, src: ADDRESS; size: CARDINAL) ;


(*
   BlockOr - performs a bitwise OR on blocks
             [dest..dest+size-1] := [dest..dest+size-1] OR
                                    [src..src+size-1]
*)

@findex BlockOr
PROCEDURE BlockOr (dest, src: ADDRESS; size: CARDINAL) ;


(*
   BlockXor - performs a bitwise XOR on blocks
              [dest..dest+size-1] := [dest..dest+size-1] XOR
                                     [src..src+size-1]
*)

@findex BlockXor
PROCEDURE BlockXor (dest, src: ADDRESS; size: CARDINAL) ;


(*
   BlockNot - performs a bitsize NOT on the block as defined
              by:  [dest..dest+size-1]
*)

@findex BlockNot
PROCEDURE BlockNot (dest: ADDRESS; size: CARDINAL) ;


(*
   BlockShr - performs a block shift right of, count, bits.
              Where the block is defined as:
              [dest..dest+size-1].
              The block is considered to be an ARRAY OF BYTEs
              which is shifted, bit at a time over each byte in
              turn.  The left most byte is considered the byte
              located at the lowest address.
              If you require an endianness SHIFT use
              the SYSTEM.SHIFT procedure and declare the
              block as a POINTER TO set type.
*)

@findex BlockShr
PROCEDURE BlockShr (dest: ADDRESS; size, count: CARDINAL) ;


(*
   BlockShl - performs a block shift left of, count, bits.
              Where the block is defined as:
              [dest..dest+size-1].
              The block is considered to be an ARRAY OF BYTEs
              which is shifted, bit at a time over each byte in
              turn.  The left most byte is considered the byte
              located at the lowest address.
              If you require an endianness SHIFT use
              the SYSTEM.SHIFT procedure and declare the
              block as a POINTER TO set type.
*)

@findex BlockShl
PROCEDURE BlockShl (dest: ADDRESS; size, count: CARDINAL) ;


(*
   BlockRor - performs a block rotate right of, count, bits.
              Where the block is defined as:
              [dest..dest+size-1].
              The block is considered to be an ARRAY OF BYTEs
              which is rotated, bit at a time over each byte in
              turn.  The left most byte is considered the byte
              located at the lowest address.
              If you require an endianness ROTATE use
              the SYSTEM.ROTATE procedure and declare the
              block as a POINTER TO set type.
*)

@findex BlockRor
PROCEDURE BlockRor (dest: ADDRESS; size, count: CARDINAL) ;


(*
   BlockRol - performs a block rotate left of, count, bits.
              Where the block is defined as:
              [dest..dest+size-1].
              The block is considered to be an ARRAY OF BYTEs
              which is rotated, bit at a time over each byte in
              turn.  The left most byte is considered the byte
              located at the lowest address.
              If you require an endianness ROTATE use
              the SYSTEM.ROTATE procedure and declare the
              block as a POINTER TO set type.
*)

@findex BlockRol
PROCEDURE BlockRol (dest: ADDRESS; size, count: CARDINAL) ;


END BitBlockOps.
@end example
@page

@node gm2-libs-pim/BitByteOps, gm2-libs-pim/BitWordOps, gm2-libs-pim/BitBlockOps, PIM and Logitech 3.0 Compatible
@subsection gm2-libs-pim/BitByteOps

@example
DEFINITION MODULE BitByteOps ;

FROM SYSTEM IMPORT BYTE ;


(*
   GetBits - returns the bits firstBit..lastBit from source.
             Bit 0 of byte maps onto the firstBit of source.
*)

@findex GetBits
PROCEDURE GetBits (source: BYTE; firstBit, lastBit: CARDINAL) : BYTE ;


(*
   SetBits - sets bits in, byte, starting at, firstBit, and ending at,
             lastBit, with, pattern.  The bit zero of, pattern, will
             be placed into, byte, at position, firstBit.
*)

@findex SetBits
PROCEDURE SetBits (VAR byte: BYTE; firstBit, lastBit: CARDINAL;
                   pattern: BYTE) ;


(*
   ByteAnd - returns a bitwise (left AND right)
*)

@findex ByteAnd
PROCEDURE ByteAnd (left, right: BYTE) : BYTE ;


(*
   ByteOr - returns a bitwise (left OR right)
*)

@findex ByteOr
PROCEDURE ByteOr (left, right: BYTE) : BYTE ;


(*
   ByteXor - returns a bitwise (left XOR right)
*)

@findex ByteXor
PROCEDURE ByteXor (left, right: BYTE) : BYTE ;


(*
   ByteNot - returns a byte with all bits inverted.
*)

@findex ByteNot
PROCEDURE ByteNot (byte: BYTE) : BYTE ;


(*
   ByteShr - returns a, byte, which has been shifted, count
             bits to the right.
*)

@findex ByteShr
PROCEDURE ByteShr (byte: BYTE; count: CARDINAL) : BYTE ;


(*
   ByteShl - returns a, byte, which has been shifted, count
             bits to the left.
*)

@findex ByteShl
PROCEDURE ByteShl (byte: BYTE; count: CARDINAL) : BYTE ;


(*
   ByteSar - shift byte arthemetic right.  Preserves the top
             end bit and as the value is shifted right.
*)

@findex ByteSar
PROCEDURE ByteSar (byte: BYTE; count: CARDINAL) : BYTE ;


(*
   ByteRor - returns a, byte, which has been rotated, count
             bits to the right.
*)

@findex ByteRor
PROCEDURE ByteRor (byte: BYTE; count: CARDINAL) : BYTE ;


(*
   ByteRol - returns a, byte, which has been rotated, count
             bits to the left.
*)

@findex ByteRol
PROCEDURE ByteRol (byte: BYTE; count: CARDINAL) : BYTE ;


(*
   HighNibble - returns the top nibble only from, byte.
                The top nibble of, byte, is extracted and
                returned in the bottom nibble of the return
                value.
*)

@findex HighNibble
PROCEDURE HighNibble (byte: BYTE) : BYTE ;


(*
   LowNibble - returns the low nibble only from, byte.
               The top nibble is replaced by zeros.
*)

@findex LowNibble
PROCEDURE LowNibble (byte: BYTE) : BYTE ;


(*
   Swap - swaps the low and high nibbles in the, byte.
*)

@findex Swap
PROCEDURE Swap (byte: BYTE) : BYTE ;


END BitByteOps.
@end example
@page

@node gm2-libs-pim/BitWordOps, gm2-libs-pim/BlockOps, gm2-libs-pim/BitByteOps, PIM and Logitech 3.0 Compatible
@subsection gm2-libs-pim/BitWordOps

@example
DEFINITION MODULE BitWordOps ;

FROM SYSTEM IMPORT WORD ;


(*
   GetBits - returns the bits firstBit..lastBit from source.
             Bit 0 of word maps onto the firstBit of source.
*)

@findex GetBits
PROCEDURE GetBits (source: WORD; firstBit, lastBit: CARDINAL) : WORD ;


(*
   SetBits - sets bits in, word, starting at, firstBit, and ending at,
             lastBit, with, pattern.  The bit zero of, pattern, will
             be placed into, word, at position, firstBit.
*)

@findex SetBits
PROCEDURE SetBits (VAR word: WORD; firstBit, lastBit: CARDINAL;
                   pattern: WORD) ;


(*
   WordAnd - returns a bitwise (left AND right)
*)

@findex WordAnd
PROCEDURE WordAnd (left, right: WORD) : WORD ;


(*
   WordOr - returns a bitwise (left OR right)
*)

@findex WordOr
PROCEDURE WordOr (left, right: WORD) : WORD ;


(*
   WordXor - returns a bitwise (left XOR right)
*)

@findex WordXor
PROCEDURE WordXor (left, right: WORD) : WORD ;


(*
   WordNot - returns a word with all bits inverted.
*)

@findex WordNot
PROCEDURE WordNot (word: WORD) : WORD ;


(*
   WordShr - returns a, word, which has been shifted, count
             bits to the right.
*)

@findex WordShr
PROCEDURE WordShr (word: WORD; count: CARDINAL) : WORD ;


(*
   WordShl - returns a, word, which has been shifted, count
             bits to the left.
*)

@findex WordShl
PROCEDURE WordShl (word: WORD; count: CARDINAL) : WORD ;


(*
   WordSar - shift word arthemetic right.  Preserves the top
             end bit and as the value is shifted right.
*)

@findex WordSar
PROCEDURE WordSar (word: WORD; count: CARDINAL) : WORD ;


(*
   WordRor - returns a, word, which has been rotated, count
             bits to the right.
*)

@findex WordRor
PROCEDURE WordRor (word: WORD; count: CARDINAL) : WORD ;


(*
   WordRol - returns a, word, which has been rotated, count
             bits to the left.
*)

@findex WordRol
PROCEDURE WordRol (word: WORD; count: CARDINAL) : WORD ;


(*
   HighByte - returns the top byte only from, word.
              The byte is returned in the bottom byte
              in the return value.
*)

@findex HighByte
PROCEDURE HighByte (word: WORD) : WORD ;


(*
   LowByte - returns the low byte only from, word.
             The byte is returned in the bottom byte
             in the return value.
*)

@findex LowByte
PROCEDURE LowByte (word: WORD) : WORD ;


(*
   Swap - byte flips the contents of word.
*)

@findex Swap
PROCEDURE Swap (word: WORD) : WORD ;


END BitWordOps.
@end example
@page

@node gm2-libs-pim/BlockOps, gm2-libs-pim/Break, gm2-libs-pim/BitWordOps, PIM and Logitech 3.0 Compatible
@subsection gm2-libs-pim/BlockOps

@example
DEFINITION MODULE BlockOps ;

FROM SYSTEM IMPORT ADDRESS ;


(*
   MoveBlockForward - moves, n, bytes from, src, to, dest.
                      Starts copying from src and keep copying
                      until, n, bytes have been copied.
*)

@findex BlockMoveForward
PROCEDURE BlockMoveForward (dest, src: ADDRESS; n: CARDINAL) ;


(*
   MoveBlockBackward - moves, n, bytes from, src, to, dest.
                       Starts copying from src+n and keeps copying
                       until, n, bytes have been copied.
                       The last datum to be copied will be the byte
                       at address, src.
*)

@findex BlockMoveBackward
PROCEDURE BlockMoveBackward (dest, src: ADDRESS; n: CARDINAL) ;


(*
   BlockClear - fills, block..block+n-1, with zero's.
*)

@findex BlockClear
PROCEDURE BlockClear (block: ADDRESS; n: CARDINAL) ;


(*
   BlockSet - fills, n, bytes starting at, block, with a pattern
              defined at address pattern..pattern+patternSize-1.
*)

@findex BlockSet
PROCEDURE BlockSet (block: ADDRESS; n: CARDINAL;
                    pattern: ADDRESS; patternSize: CARDINAL) ;


(*
   BlockEqual - returns TRUE if the blocks defined, a..a+n-1, and,
                b..b+n-1 contain the same bytes.
*)

@findex BlockEqual
PROCEDURE BlockEqual (a, b: ADDRESS; n: CARDINAL) : BOOLEAN ;


(*
   BlockPosition - searches for a pattern as defined by
                   pattern..patternSize-1 in the block,
                   block..block+blockSize-1.  It returns
                   the offset from block indicating the
                   first occurence of, pattern.
                   MAX(CARDINAL) is returned if no match
                   is detected.
*)

@findex BlockPosition
PROCEDURE BlockPosition (block: ADDRESS; blockSize: CARDINAL;
                         pattern: ADDRESS; patternSize: CARDINAL) : CARDINAL ;


END BlockOps.
@end example
@page

@node gm2-libs-pim/Break, gm2-libs-pim/CardinalIO, gm2-libs-pim/BlockOps, PIM and Logitech 3.0 Compatible
@subsection gm2-libs-pim/Break

@example
DEFINITION MODULE Break ;


EXPORT QUALIFIED EnableBreak, DisableBreak, InstallBreak, UnInstallBreak ;


(*
   EnableBreak - enable the current break handler.
*)

@findex EnableBreak
PROCEDURE EnableBreak ;


(*
   DisableBreak - disable the current break handler (and all
                  installed handlers).
*)

@findex DisableBreak
PROCEDURE DisableBreak ;


(*
   InstallBreak - installs a procedure, p, to be invoked when
                  a ctrl-c is caught. Any number of these
                  procedures may be stacked. Only the top
                  procedure is run when ctrl-c is caught.
*)

@findex InstallBreak
PROCEDURE InstallBreak (p: PROC) ;


(*
   UnInstallBreak - pops the break handler stack.
*)

@findex UnInstallBreak
PROCEDURE UnInstallBreak ;


END Break.
@end example
@page

@node gm2-libs-pim/CardinalIO, gm2-libs-pim/Conversions, gm2-libs-pim/Break, PIM and Logitech 3.0 Compatible
@subsection gm2-libs-pim/CardinalIO

@example
DEFINITION MODULE CardinalIO ;

EXPORT QUALIFIED Done,
                 ReadCardinal, WriteCardinal, ReadHex, WriteHex,
                 ReadLongCardinal, WriteLongCardinal, ReadLongHex,
                 WriteLongHex,
                 ReadShortCardinal, WriteShortCardinal, ReadShortHex,
                 WriteShortHex ;


VAR
@findex Done (var)
   Done: BOOLEAN ;


(*
   ReadCardinal - read an unsigned decimal number from the terminal.
                  The read continues until a space, newline, esc or
                  end of file is reached.
*)

@findex ReadCardinal
PROCEDURE ReadCardinal (VAR c: CARDINAL) ;


(*
   WriteCardinal - writes the value, c, to the terminal and ensures
                   that at least, n, characters are written. The number
                   will be padded out by preceeding spaces if necessary.
*)

@findex WriteCardinal
PROCEDURE WriteCardinal (c: CARDINAL; n: CARDINAL) ;


(*
   ReadHex - reads in an unsigned hexadecimal number from the terminal.
             The read continues until a space, newline, esc or
             end of file is reached.
*)

@findex ReadHex
PROCEDURE ReadHex (VAR c: CARDINAL) ;


(*
   WriteHex - writes out a CARDINAL, c, in hexadecimal format padding
              with, n, characters (leading with '0')
*)

@findex WriteHex
PROCEDURE WriteHex (c: CARDINAL; n: CARDINAL) ;


(*
   ReadLongCardinal - read an unsigned decimal number from the terminal.
                      The read continues until a space, newline, esc or
                      end of file is reached.
*)

@findex ReadLongCardinal
PROCEDURE ReadLongCardinal (VAR c: LONGCARD) ;


(*
   WriteLongCardinal - writes the value, c, to the terminal and ensures
                       that at least, n, characters are written. The number
                       will be padded out by preceeding spaces if necessary.
*)

@findex WriteLongCardinal
PROCEDURE WriteLongCardinal (c: LONGCARD; n: CARDINAL) ;


(*
   ReadLongHex - reads in an unsigned hexadecimal number from the terminal.
                 The read continues until a space, newline, esc or
                 end of file is reached.
*)

@findex ReadLongHex
PROCEDURE ReadLongHex (VAR c: LONGCARD) ;


(*
   WriteLongHex - writes out a LONGCARD, c, in hexadecimal format padding
                  with, n, characters (leading with '0')
*)

@findex WriteLongHex
PROCEDURE WriteLongHex (c: LONGCARD; n: CARDINAL) ;


(*
   WriteShortCardinal - writes the value, c, to the terminal and ensures
                       that at least, n, characters are written. The number
                       will be padded out by preceeding spaces if necessary.
*)

@findex WriteShortCardinal
PROCEDURE WriteShortCardinal (c: SHORTCARD; n: CARDINAL) ;


(*
   ReadShortCardinal - read an unsigned decimal number from the terminal.
                       The read continues until a space, newline, esc or
                       end of file is reached.
*)

@findex ReadShortCardinal
PROCEDURE ReadShortCardinal (VAR c: SHORTCARD) ;


(*
   ReadShortHex - reads in an unsigned hexadecimal number from the terminal.
                 The read continues until a space, newline, esc or
                 end of file is reached.
*)

@findex ReadShortHex
PROCEDURE ReadShortHex (VAR c: SHORTCARD) ;


(*
   WriteShortHex - writes out a SHORTCARD, c, in hexadecimal format padding
                  with, n, characters (leading with '0')
*)

@findex WriteShortHex
PROCEDURE WriteShortHex (c: SHORTCARD; n: CARDINAL) ;


END CardinalIO.
@end example
@page

@node gm2-libs-pim/Conversions, gm2-libs-pim/DebugPMD, gm2-libs-pim/CardinalIO, PIM and Logitech 3.0 Compatible
@subsection gm2-libs-pim/Conversions

@example
DEFINITION MODULE Conversions ;

EXPORT QUALIFIED ConvertOctal, ConvertHex, ConvertCardinal,
                 ConvertInteger, ConvertLongInt, ConvertShortInt ;

(*
   ConvertOctal - converts a CARDINAL, num, into an octal/hex/decimal
                  string and right justifies the string. It adds
                  spaces rather than '0' to pad out the string
                  to len characters.

                  If the length of str is < num then the number is
                  truncated on the right.
*)

@findex ConvertOctal
PROCEDURE ConvertOctal    (num, len: CARDINAL; VAR str: ARRAY OF CHAR) ;
@findex ConvertHex
PROCEDURE ConvertHex      (num, len: CARDINAL; VAR str: ARRAY OF CHAR) ;
@findex ConvertCardinal
PROCEDURE ConvertCardinal (num, len: CARDINAL; VAR str: ARRAY OF CHAR) ;

(*
   The INTEGER counterparts will add a '-' if, num, is <0
*)

@findex ConvertInteger
PROCEDURE ConvertInteger  (num: INTEGER; len: CARDINAL; VAR str: ARRAY OF CHAR) ;
@findex ConvertLongInt
PROCEDURE ConvertLongInt  (num: LONGINT; len: CARDINAL; VAR str: ARRAY OF CHAR) ;
@findex ConvertShortInt
PROCEDURE ConvertShortInt (num: SHORTINT; len: CARDINAL; VAR str: ARRAY OF CHAR) ;


END Conversions.
@end example
@page

@node gm2-libs-pim/DebugPMD, gm2-libs-pim/DebugTrace, gm2-libs-pim/Conversions, PIM and Logitech 3.0 Compatible
@subsection gm2-libs-pim/DebugPMD

@example
DEFINITION MODULE DebugPMD ;

END DebugPMD.
@end example
@page

@node gm2-libs-pim/DebugTrace, gm2-libs-pim/Delay, gm2-libs-pim/DebugPMD, PIM and Logitech 3.0 Compatible
@subsection gm2-libs-pim/DebugTrace

@example
DEFINITION MODULE DebugTrace ;

END DebugTrace.
@end example
@page

@node gm2-libs-pim/Delay, gm2-libs-pim/Display, gm2-libs-pim/DebugTrace, PIM and Logitech 3.0 Compatible
@subsection gm2-libs-pim/Delay

@example
DEFINITION MODULE Delay ;

EXPORT QUALIFIED Delay ;


(*
   milliSec - delays the program by approximately, milliSec, milliseconds.
*)

@findex Delay
PROCEDURE Delay (milliSec: INTEGER) ;


END Delay.
@end example
@page

@node gm2-libs-pim/Display, gm2-libs-pim/ErrorCode, gm2-libs-pim/Delay, PIM and Logitech 3.0 Compatible
@subsection gm2-libs-pim/Display

@example
DEFINITION MODULE Display ;

EXPORT QUALIFIED Write ;


(*
   Write - display a character to the stdout.
           ASCII.EOL moves to the beginning of the next line.
           ASCII.del erases the character to the left of the cursor.
*)

@findex Write
PROCEDURE Write (ch: CHAR) ;


END Display.
@end example
@page

@node gm2-libs-pim/ErrorCode, gm2-libs-pim/FileSystem, gm2-libs-pim/Display, PIM and Logitech 3.0 Compatible
@subsection gm2-libs-pim/ErrorCode

@example
DEFINITION MODULE ErrorCode ;

EXPORT QUALIFIED SetErrorCode, GetErrorCode, ExitToOS ;


(*
   SetErrorCode - sets the exit value which will be used if
                  the application terminates normally.
*)

@findex SetErrorCode
PROCEDURE SetErrorCode (value: INTEGER) ;


(*
   GetErrorCode - returns the current value to be used upon
                  application termination.
*)

@findex GetErrorCode
PROCEDURE GetErrorCode (VAR value: INTEGER) ;


(*
   ExitToOS - terminate the application and exit returning
              the last value set by SetErrorCode to the OS.
*)

@findex ExitToOS
PROCEDURE ExitToOS ;


END ErrorCode.
@end example
@page

@node gm2-libs-pim/FileSystem, gm2-libs-pim/FloatingUtilities, gm2-libs-pim/ErrorCode, PIM and Logitech 3.0 Compatible
@subsection gm2-libs-pim/FileSystem

@example
DEFINITION MODULE FileSystem ;

(*  Use this module sparingly, FIO or the ISO file modules have a
    much cleaner interface.  *)

FROM SYSTEM IMPORT WORD, BYTE, ADDRESS ;
IMPORT FIO ;
FROM DynamicStrings IMPORT String ;

EXPORT QUALIFIED File, Response, Flag, FlagSet,

                 Create, Close, Lookup, Rename, Delete,
                 SetRead, SetWrite, SetModify, SetOpen,
                 Doio, SetPos, GetPos, Length, Reset,

                 ReadWord, ReadChar, ReadByte, ReadNBytes,
                 WriteWord, WriteChar, WriteByte, WriteNBytes ;

TYPE
@findex File (type)
   File = RECORD
             res     : Response ;
             flags   : FlagSet ;
             eof     : BOOLEAN ;
             lastWord: WORD ;
             lastByte: BYTE ;
             fio     : FIO.File ;
             highpos,
             lowpos  : CARDINAL ;
             name    : String ;
@findex END (type)
          END ;

@findex Flag (type)
   Flag = (
           read,        (* read access mode *)
           write,       (* write access mode *)
           modify,
           truncate,    (* truncate file when closed *)
           again,       (* reread the last character *)
           temporary,   (* file is temporary *)
           opened       (* file has been opened *)
          );

@findex FlagSet (type)
   FlagSet = SET OF Flag;

@findex Response (type)
   Response = (done, notdone, notsupported, callerror,
               unknownfile, paramerror, toomanyfiles,
@findex userdeverror) (type)
               userdeverror) ;

@findex Command (type)
   Command = (create, close, lookup, rename, delete,
              setread, setwrite, setmodify, setopen,
              doio, setpos, getpos, length) ;


(*
   Create - creates a temporary file. To make the file perminant
            the file must be renamed.
*)

@findex Create
PROCEDURE Create (VAR f: File) ;


(*
   Close - closes an open file.
*)

@findex Close
PROCEDURE Close (f: File) ;


(*
   Lookup - looks for a file, filename. If the file is found
            then, f, is opened. If it is not found and, newFile,
            is TRUE then a new file is created and attached to, f.
            If, newFile, is FALSE and no file was found then f.res
            is set to notdone.
*)

@findex Lookup
PROCEDURE Lookup (VAR f: File; filename: ARRAY OF CHAR; newFile: BOOLEAN) ;


(*
   Rename - rename a file and change a temporary file to a permanent
            file. f.res is set appropriately.
*)

@findex Rename
PROCEDURE Rename (VAR f: File; newname: ARRAY OF CHAR) ;


(*
   Delete - deletes a file, name, and sets the f.res field.
            f.res is set appropriately.
*)

@findex Delete
PROCEDURE Delete (name: ARRAY OF CHAR; VAR f: File) ;


(*
   ReadWord - reads a WORD, w, from file, f.
              f.res is set appropriately.
*)

@findex ReadWord
PROCEDURE ReadWord (VAR f: File; VAR w: WORD) ;


(*
   WriteWord - writes one word to a file, f.
               f.res is set appropriately.
*)

@findex WriteWord
PROCEDURE WriteWord (VAR f: File; w: WORD) ;


(*
   ReadChar - reads one character from a file, f.
*)

@findex ReadChar
PROCEDURE ReadChar (VAR f: File; VAR ch: CHAR) ;


(*
   WriteChar - writes a character, ch, to a file, f.
               f.res is set appropriately.
*)

@findex WriteChar
PROCEDURE WriteChar (VAR f: File; ch: CHAR) ;


(*
   ReadByte - reads a BYTE, b, from file, f.
              f.res is set appropriately.
*)

@findex ReadByte
PROCEDURE ReadByte (VAR f: File; VAR b: BYTE) ;


(*
   WriteByte - writes one BYTE, b, to a file, f.
               f.res is set appropriately.
*)

@findex WriteByte
PROCEDURE WriteByte (VAR f: File; b: BYTE) ;


(*
   ReadNBytes - reads a sequence of bytes from a file, f.
*)

@findex ReadNBytes
PROCEDURE ReadNBytes (VAR f: File; a: ADDRESS; amount: CARDINAL;
                      VAR actuallyRead: CARDINAL) ;


(*
   WriteNBytes - writes a sequence of bytes to file, f.
*)

@findex WriteNBytes
PROCEDURE WriteNBytes (VAR f: File; a: ADDRESS; amount: CARDINAL;
                       VAR actuallyWritten: CARDINAL) ;


(*
   Again - returns the last character read to the internal buffer
           so that it can be read again.
*)

@findex Again
PROCEDURE Again (VAR f: File) ;


(*
   SetRead - puts the file, f, into the read state.
             The file position is unchanged.
*)

@findex SetRead
PROCEDURE SetRead (VAR f: File) ;


(*
   SetWrite - puts the file, f, into the write state.
              The file position is unchanged.
*)

@findex SetWrite
PROCEDURE SetWrite (VAR f: File) ;


(*
   SetModify - puts the file, f, into the modify state.
               The file position is unchanged but the file can be
               read and written.
*)

@findex SetModify
PROCEDURE SetModify (VAR f: File) ;


(*
   SetOpen - places a file, f, into the open state. The file may
             have been in the read/write/modify state before and
             in which case the previous buffer contents are flushed
             and the file state is reset to open. The position is
             unaltered.
*)

@findex SetOpen
PROCEDURE SetOpen (VAR f: File) ;


(*
   Reset - places a file, f, into the open state and reset the
           position to the start of the file.
*)

@findex Reset
PROCEDURE Reset (VAR f: File) ;


(*
   SetPos - lseek to a position within a file.
*)

@findex SetPos
PROCEDURE SetPos (VAR f: File; high, low: CARDINAL) ;


(*
   GetPos - return the position within a file.
*)

@findex GetPos
PROCEDURE GetPos (VAR f: File; VAR high, low: CARDINAL) ;


(*
   Length - returns the length of file, in, high, and, low.
*)

@findex Length
PROCEDURE Length (VAR f: File; VAR high, low: CARDINAL) ;


(*
   Doio - effectively flushes a file in write mode, rereads the
          current buffer from disk if in read mode and writes
          and rereads the buffer if in modify mode.
*)

@findex Doio
PROCEDURE Doio (VAR f: File) ;


(*
   FileNameChar - checks to see whether the character, ch, is
                  legal in a filename. nul is returned if the
                  character was illegal.
*)

@findex FileNameChar
PROCEDURE FileNameChar (ch: CHAR) ;


END FileSystem.
@end example
@page

@node gm2-libs-pim/FloatingUtilities, gm2-libs-pim/InOut, gm2-libs-pim/FileSystem, PIM and Logitech 3.0 Compatible
@subsection gm2-libs-pim/FloatingUtilities

@example
DEFINITION MODULE FloatingUtilities ;

EXPORT QUALIFIED Frac, Round, Float, Trunc,
                 Fracl, Roundl, Floatl, Truncl ;


(*
   Frac - returns the fractional component of, r.
*)

@findex Frac
PROCEDURE Frac (r: REAL) : REAL ;


(*
   Int - returns the integer part of r. It rounds the value towards zero.
*)

@findex Int
PROCEDURE Int (r: REAL) : INTEGER ;


(*
   Round - returns the number rounded to the nearest integer.
*)

@findex Round
PROCEDURE Round (r: REAL) : INTEGER ;


(*
   Float - returns a REAL value corresponding to, i.
*)

@findex Float
PROCEDURE Float (i: INTEGER) : REAL ;


(*
   Trunc - round to the nearest integer not larger in absolute
           value.
*)

@findex Trunc
PROCEDURE Trunc (r: REAL) : INTEGER ;


(*
   Fracl - returns the fractional component of, r.
*)

@findex Fracl
PROCEDURE Fracl (r: LONGREAL) : LONGREAL ;


(*
   Intl - returns the integer part of r. It rounds the value towards zero.
*)

@findex Intl
PROCEDURE Intl (r: LONGREAL) : LONGINT ;


(*
   Roundl - returns the number rounded to the nearest integer.
*)

@findex Roundl
PROCEDURE Roundl (r: LONGREAL) : LONGINT ;


(*
   Floatl - returns a REAL value corresponding to, i.
*)

@findex Floatl
PROCEDURE Floatl (i: INTEGER) : LONGREAL ;


(*
   Truncl - round to the nearest integer not larger in absolute
            value.
*)

@findex Truncl
PROCEDURE Truncl (r: LONGREAL) : LONGINT ;


END FloatingUtilities.
@end example
@page

@node gm2-libs-pim/InOut, gm2-libs-pim/Keyboard, gm2-libs-pim/FloatingUtilities, PIM and Logitech 3.0 Compatible
@subsection gm2-libs-pim/InOut

@example
DEFINITION MODULE InOut ;

IMPORT ASCII ;
FROM DynamicStrings IMPORT String ;
EXPORT QUALIFIED EOL, Done, termCH, OpenInput, OpenOutput,
                 CloseInput, CloseOutput,
                 Read, ReadString, ReadInt, ReadCard,
                 Write, WriteLn, WriteString, WriteInt, WriteCard,
                 WriteOct, WriteHex,
                 ReadS, WriteS ;

CONST
@findex EOL (const)
   EOL = ASCII.EOL ;

VAR
@findex Done (var)
   Done  : BOOLEAN ;
@findex termCH (var)
   termCH: CHAR ;


(*
   OpenInput - reads a string from stdin as the filename for reading.
               If the filename ends with `.' then it appends the defext
               extension. The global variable Done is set if all
               was successful.
*)

@findex OpenInput
PROCEDURE OpenInput (defext: ARRAY OF CHAR) ;


(*
   CloseInput - closes an opened input file and returns input back to
                StdIn.
*)

@findex CloseInput
PROCEDURE CloseInput ;


(*
   OpenOutput - reads a string from stdin as the filename for writing.
                If the filename ends with `.' then it appends the defext
                extension. The global variable Done is set if all
                was successful.
*)

@findex OpenOutput
PROCEDURE OpenOutput (defext: ARRAY OF CHAR) ;


(*
   CloseOutput - closes an opened output file and returns output back to
                 StdOut.
*)

@findex CloseOutput
PROCEDURE CloseOutput ;


(*
   Read - reads a single character from the current input file.
          Done is set to FALSE if end of file is reached or an
          error occurs.
*)

@findex Read
PROCEDURE Read (VAR ch: CHAR) ;


(*
   ReadString - reads a sequence of characters. Leading white space
                is ignored and the string is terminated with a character
                <= ' '
*)

@findex ReadString
PROCEDURE ReadString (VAR s: ARRAY OF CHAR) ;


(*
   WriteString - writes a string to the output file.
*)

@findex WriteString
PROCEDURE WriteString (s: ARRAY OF CHAR) ;


(*
   Write - writes out a single character, ch, to the current output file.
*)

@findex Write
PROCEDURE Write (ch: CHAR) ;


(*
   WriteLn - writes a newline to the output file.
*)

@findex WriteLn
PROCEDURE WriteLn ;


(*
   ReadInt - reads a string and converts it into an INTEGER, x.
             Done is set if an INTEGER is read.
*)

@findex ReadInt
PROCEDURE ReadInt (VAR x: INTEGER) ;


(*
   ReadInt - reads a string and converts it into an INTEGER, x.
             Done is set if an INTEGER is read.
*)

@findex ReadCard
PROCEDURE ReadCard (VAR x: CARDINAL) ;


(*
   WriteCard - writes the CARDINAL, x, to the output file. It ensures
               that the number occupies, n, characters. Leading spaces
               are added if required.
*)

@findex WriteCard
PROCEDURE WriteCard (x, n: CARDINAL) ;


(*
   WriteInt - writes the INTEGER, x, to the output file. It ensures
              that the number occupies, n, characters. Leading spaces
              are added if required.
*)

@findex WriteInt
PROCEDURE WriteInt (x: INTEGER; n: CARDINAL) ;


(*
   WriteOct - writes the CARDINAL, x, to the output file in octal.
              It ensures that the number occupies, n, characters.
              Leading spaces are added if required.
*)

@findex WriteOct
PROCEDURE WriteOct (x, n: CARDINAL) ;


(*
   WriteHex - writes the CARDINAL, x, to the output file in hexadecimal.
              It ensures that the number occupies, n, characters.
              Leading spaces are added if required.
*)

@findex WriteHex
PROCEDURE WriteHex (x, n: CARDINAL) ;


(*
   ReadS - returns a string which has is a sequence of characters.
           Leading white space is ignored and string is terminated
           with a character <= ' '.
*)

@findex ReadS
PROCEDURE ReadS () : String ;


(*
   WriteS - writes a String to the output device.
            It returns the string, s.
*)

@findex WriteS
PROCEDURE WriteS (s: String) : String ;


END InOut.
@end example
@page

@node gm2-libs-pim/Keyboard, gm2-libs-pim/LongIO, gm2-libs-pim/InOut, PIM and Logitech 3.0 Compatible
@subsection gm2-libs-pim/Keyboard

@example
DEFINITION MODULE Keyboard ;

EXPORT QUALIFIED Read, KeyPressed ;


(*
   Read - reads a character from StdIn. If necessary it will wait
          for a key to become present on StdIn.
*)

@findex Read
PROCEDURE Read (VAR ch: CHAR) ;


(*
   KeyPressed - returns TRUE if a character can be read from StdIn
                without blocking the caller.
*)

@findex KeyPressed
PROCEDURE KeyPressed () : BOOLEAN ;


END Keyboard.
@end example
@page

@node gm2-libs-pim/LongIO, gm2-libs-pim/NumberConversion, gm2-libs-pim/Keyboard, PIM and Logitech 3.0 Compatible
@subsection gm2-libs-pim/LongIO

@example
DEFINITION MODULE LongIO ;

EXPORT QUALIFIED Done, ReadLongInt, WriteLongInt ;

VAR
@findex Done (var)
   Done: BOOLEAN ;

@findex ReadLongInt
PROCEDURE ReadLongInt (VAR i: LONGINT) ;
@findex WriteLongInt
PROCEDURE WriteLongInt (i: LONGINT; n: CARDINAL) ;


END LongIO.
@end example
@page

@node gm2-libs-pim/NumberConversion, gm2-libs-pim/Random, gm2-libs-pim/LongIO, PIM and Logitech 3.0 Compatible
@subsection gm2-libs-pim/NumberConversion

@example
DEFINITION MODULE NumberConversion ;

(* --fixme-- finish this.  *)

END NumberConversion.
@end example
@page

@node gm2-libs-pim/Random, gm2-libs-pim/RealConversions, gm2-libs-pim/NumberConversion, PIM and Logitech 3.0 Compatible
@subsection gm2-libs-pim/Random

@example
DEFINITION MODULE Random ;

FROM SYSTEM IMPORT BYTE ;
EXPORT QUALIFIED Randomize, RandomInit, RandomBytes, RandomCard, RandomInt, RandomReal, RandomLongReal ;


(*
   Randomize - initialize the random number generator with a seed
               based on the microseconds.
*)

@findex Randomize
PROCEDURE Randomize ;


(*
   RandomInit - initialize the random number generator with value, seed.
*)

@findex RandomInit
PROCEDURE RandomInit (seed: CARDINAL) ;


(*
   RandomBytes - fills in an array with random values.
*)

@findex RandomBytes
PROCEDURE RandomBytes (VAR a: ARRAY OF BYTE) ;


(*
   RandomInt - return an INTEGER in the range 0..bound-1
*)

@findex RandomInt
PROCEDURE RandomInt (bound: INTEGER) : INTEGER ;


(*
   RandomCard - return a CARDINAL in the range 0..bound-1
*)

@findex RandomCard
PROCEDURE RandomCard (bound: CARDINAL) : CARDINAL ;


(*
   RandomReal - return a REAL number in the range 0.0..1.0
*)

@findex RandomReal
PROCEDURE RandomReal () : REAL ;


(*
   RandomLongReal - return a LONGREAL number in the range 0.0..1.0
*)

@findex RandomLongReal
PROCEDURE RandomLongReal () : LONGREAL ;


END Random.
@end example
@page

@node gm2-libs-pim/RealConversions, gm2-libs-pim/RealInOut, gm2-libs-pim/Random, PIM and Logitech 3.0 Compatible
@subsection gm2-libs-pim/RealConversions

@example
DEFINITION MODULE RealConversions ;

EXPORT QUALIFIED SetNoOfExponentDigits,
                 RealToString, StringToReal,
                 LongRealToString, StringToLongReal ;


(*
   SetNoOfExponentDigits - sets the number of exponent digits to be
                           used during future calls of LongRealToString
                           and RealToString providing that the width
                           is sufficient.
                           If this value is set to 0 (the default) then
                           the number digits used is the minimum necessary.
*)

@findex SetNoOfExponentDigits
PROCEDURE SetNoOfExponentDigits (places: CARDINAL) ;


(*
   RealToString - converts a real, r, into a right justified string, str.
                  The number of digits to the right of the decimal point
                  is given in, digits.  The value, width, represents the
                  maximum number of characters to be used in the string,
                  str.

                  If digits is negative then exponent notation is used
                  whereas if digits is positive then fixed point notation
                  is used.

                  If, r, is less than 0.0 then a '-' preceeds the value,
                  str.  However, if, r, is >= 0.0 a '+' is not added.

                  If the conversion of, r, to a string requires more
                  than, width, characters then the string, str, is set
                  to a nul string and, ok is assigned FALSE.

                  For fixed point notation the minimum width required is
                  ABS(width)+8

                  For exponent notation the minimum width required is
                  ABS(digits)+2+log10(magnitude).

                  if r is a NaN then the string 'nan' is returned formatted and
                  ok will be FALSE.
*)

@findex RealToString
PROCEDURE RealToString (r: REAL; digits, width: INTEGER;
                        VAR str: ARRAY OF CHAR; VAR ok: BOOLEAN) ;


(*
   LongRealToString - converts a real, r, into a right justified string, str.
                      The number of digits to the right of the decimal point
                      is given in, digits. The value, width, represents the
                      maximum number of characters to be used in the string,
                      str.

                      If digits is negative then exponent notation is used
                      whereas if digits is positive then fixed point notation
                      is used.

                      If, r, is less than 0.0 then a '-' preceeds the value,
                      str. However, if, r, is >= 0.0 a '+' is not added.

                      If the conversion of, r, to a string requires more
                      than, width, characters then the string, str, is set
                      to a nul string and, ok is assigned FALSE.

                      For fixed point notation the minimum width required is
                      ABS(width)+8

                      For exponent notation the minimum width required is
                      ABS(digits)+2+log10(magnitude).

                      Examples:
                      RealToString(100.0, 10, 10, a, ok)       ->  '100.000000'
                      RealToString(100.0, -5, 12, a, ok)       ->  '  1.00000E+2'

                      RealToString(123.456789, 10, 10, a, ok)  ->  '123.456789'
                      RealToString(123.456789, -5, 13, a, ok)  ->  '    1.23456E+2'

                      RealToString(123.456789, -2, 15, a, ok)  ->  '          1.23E+2'

                      if r is a NaN then the string 'nan' is returned formatted and
                      ok will be FALSE.
*)

@findex LongRealToString
PROCEDURE LongRealToString (r: LONGREAL; digits, width: INTEGER;
                            VAR str: ARRAY OF CHAR; VAR ok: BOOLEAN) ;


(*
   StringToReal - converts, str, into a REAL, r. The parameter, ok, is
                  set to TRUE if the conversion was successful.
*)

@findex StringToReal
PROCEDURE StringToReal (str: ARRAY OF CHAR; VAR r: REAL; VAR ok: BOOLEAN) ;


(*
   StringToLongReal - converts, str, into a LONGREAL, r. The parameter, ok, is
                      set to TRUE if the conversion was successful.
*)

@findex StringToLongReal
PROCEDURE StringToLongReal (str: ARRAY OF CHAR; VAR r: LONGREAL; VAR ok: BOOLEAN) ;


END RealConversions.
@end example
@page

@node gm2-libs-pim/RealInOut, gm2-libs-pim/Strings, gm2-libs-pim/RealConversions, PIM and Logitech 3.0 Compatible
@subsection gm2-libs-pim/RealInOut

@example
DEFINITION MODULE RealInOut ;

EXPORT QUALIFIED SetNoOfDecimalPlaces,
                 ReadReal, WriteReal, WriteRealOct,
                 ReadLongReal, WriteLongReal, WriteLongRealOct,
                 ReadShortReal, WriteShortReal, WriteShortRealOct,
                 Done ;

CONST
@findex DefaultDecimalPlaces (const)
   DefaultDecimalPlaces = 6 ;

VAR
@findex Done (var)
   Done: BOOLEAN ;


(*
   SetNoOfDecimalPlaces - number of decimal places WriteReal and
                          WriteLongReal should emit.  This procedure
                          can be used to override the default
                          DefaultDecimalPlaces constant.
*)

@findex SetNoOfDecimalPlaces
PROCEDURE SetNoOfDecimalPlaces (places: CARDINAL) ;


(*
   ReadReal - reads a real number, legal syntaxes include:
              100, 100.0, 100e0, 100E0, 100E-1, E2, +1E+2, 1e+2
*)

@findex ReadReal
PROCEDURE ReadReal (VAR x: REAL) ;


(*
   WriteReal - writes a real to the terminal. The real number
               is right justified and, n, is the minimum field
               width.
*)

@findex WriteReal
PROCEDURE WriteReal (x: REAL; n: CARDINAL) ;


(*
   WriteRealOct - writes the real to terminal in octal words.
*)

@findex WriteRealOct
PROCEDURE WriteRealOct (x: REAL) ;


(*
   ReadLongReal - reads a LONGREAL number, legal syntaxes include:
                  100, 100.0, 100e0, 100E0, 100E-1, E2, +1E+2, 1e+2
*)

@findex ReadLongReal
PROCEDURE ReadLongReal (VAR x: LONGREAL) ;


(*
   WriteLongReal - writes a LONGREAL to the terminal. The real number
                   is right justified and, n, is the minimum field
                   width.
*)

@findex WriteLongReal
PROCEDURE WriteLongReal (x: LONGREAL; n: CARDINAL) ;


(*
   WriteLongRealOct - writes the LONGREAL to terminal in octal words.
*)

@findex WriteLongRealOct
PROCEDURE WriteLongRealOct (x: LONGREAL) ;


(*
   ReadShortReal - reads a SHORTREAL number, legal syntaxes include:
                   100, 100.0, 100e0, 100E0, 100E-1, E2, +1E+2, 1e+2
*)

@findex ReadShortReal
PROCEDURE ReadShortReal (VAR x: SHORTREAL) ;


(*
   WriteShortReal - writes a SHORTREAL to the terminal. The real number
                    is right justified and, n, is the minimum field
                    width.
*)

@findex WriteShortReal
PROCEDURE WriteShortReal (x: SHORTREAL; n: CARDINAL) ;


(*
   WriteShortRealOct - writes the SHORTREAL to terminal in octal words.
*)

@findex WriteShortRealOct
PROCEDURE WriteShortRealOct (x: SHORTREAL) ;


END RealInOut.
@end example
@page

@node gm2-libs-pim/Strings, gm2-libs-pim/Termbase, gm2-libs-pim/RealInOut, PIM and Logitech 3.0 Compatible
@subsection gm2-libs-pim/Strings

@example
DEFINITION MODULE Strings ;

EXPORT QUALIFIED Assign, Insert, Delete, Pos, Copy, ConCat, Length,
                 CompareStr ;

(*
   Assign - dest := source.
*)

@findex Assign
PROCEDURE Assign (VAR dest: ARRAY OF CHAR; source: ARRAY OF CHAR) ;


(*
   Insert - insert the string, substr, into str at position, index.
            substr, is added to the end of, str, if, index >= length(str)
*)

@findex Insert
PROCEDURE Insert (substr: ARRAY OF CHAR; VAR str: ARRAY OF CHAR;
                  index: CARDINAL) ;


(*
   Delete - delete len characters from, str, starting at, index.
*)

@findex Delete
PROCEDURE Delete (VAR str: ARRAY OF CHAR; index: CARDINAL; length: CARDINAL) ;


(*
   Pos - return the first position of, substr, in, str.
*)

@findex Pos
PROCEDURE Pos (substr, str: ARRAY OF CHAR) : CARDINAL ;


(*
   Copy - copy at most, length, characters in, substr, to, str,
          starting at position, index.
*)

@findex Copy
PROCEDURE Copy (str: ARRAY OF CHAR;
                index, length: CARDINAL; VAR result: ARRAY OF CHAR) ;

(*
   ConCat - concatenates two strings, s1, and, s2
            and places the result into, dest.
*)

@findex ConCat
PROCEDURE ConCat (s1, s2: ARRAY OF CHAR; VAR dest: ARRAY OF CHAR) ;


(*
   Length - return the length of string, s.
*)

@findex Length
PROCEDURE Length (s: ARRAY OF CHAR) : CARDINAL ;


(*
   CompareStr - compare two strings, left, and, right.
*)

@findex CompareStr
PROCEDURE CompareStr (left, right: ARRAY OF CHAR) : INTEGER ;


END Strings.
@end example
@page

@node gm2-libs-pim/Termbase, gm2-libs-pim/Terminal, gm2-libs-pim/Strings, PIM and Logitech 3.0 Compatible
@subsection gm2-libs-pim/Termbase

@example
DEFINITION MODULE Termbase ;

(*
   Initially the read routines from Keyboard and the
   write routine from Display is assigned to the Read,
   KeyPressed and Write procedures.
*)

EXPORT QUALIFIED ReadProcedure, StatusProcedure, WriteProcedure,
                 AssignRead, AssignWrite, UnAssignRead, UnAssignWrite,
                 Read, KeyPressed, Write ;

TYPE
@findex ReadProcedure (type)
   ReadProcedure = PROCEDURE (VAR CHAR) ;
@findex WriteProcedure (type)
   WriteProcedure = PROCEDURE (CHAR) ;
@findex StatusProcedure (type)
   StatusProcedure = PROCEDURE () : BOOLEAN ;


(*
   AssignRead - assigns a read procedure and status procedure for terminal
                input. Done is set to TRUE if successful. Subsequent
                Read and KeyPressed calls are mapped onto the user supplied
                procedures. The previous read and status procedures are
                uncovered and reused after UnAssignRead is called.
*)

@findex AssignRead
PROCEDURE AssignRead (rp: ReadProcedure; sp: StatusProcedure;
                      VAR Done: BOOLEAN) ;


(*
   UnAssignRead - undo the last call to AssignRead and set Done to TRUE
                  on success.
*)

@findex UnAssignRead
PROCEDURE UnAssignRead (VAR Done: BOOLEAN) ;


(*
   Read - reads a single character using the currently active read
          procedure.
*)

@findex Read
PROCEDURE Read (VAR ch: CHAR) ;


(*
   KeyPressed - returns TRUE if a character is available to be read.
*)

@findex KeyPressed
PROCEDURE KeyPressed () : BOOLEAN ;


(*
   AssignWrite - assigns a write procedure for terminal output.
                 Done is set to TRUE if successful. Subsequent
                 Write calls are mapped onto the user supplied
                 procedure. The previous write procedure is
                 uncovered and reused after UnAssignWrite is called.
*)

@findex AssignWrite
PROCEDURE AssignWrite (wp: WriteProcedure; VAR Done: BOOLEAN) ;


(*
   UnAssignWrite - undo the last call to AssignWrite and set Done to TRUE
                   on success.
*)

@findex UnAssignWrite
PROCEDURE UnAssignWrite (VAR Done: BOOLEAN) ;


(*
   Write - writes a single character using the currently active write
           procedure.
*)

@findex Write
PROCEDURE Write (VAR ch: CHAR) ;


END Termbase.
@end example
@page

@node gm2-libs-pim/Terminal, gm2-libs-pim/TimeDate, gm2-libs-pim/Termbase, PIM and Logitech 3.0 Compatible
@subsection gm2-libs-pim/Terminal

@example
DEFINITION MODULE Terminal ;

(*
   It provides simple terminal input output
   routines which all utilize the TermBase module.
*)

EXPORT QUALIFIED Read, KeyPressed, ReadAgain, ReadString, Write,
                 WriteString, WriteLn ;


(*
   Read - reads a single character.
*)

@findex Read
PROCEDURE Read (VAR ch: CHAR) ;


(*
   KeyPressed - returns TRUE if a character can be read without blocking
                the caller.
*)

@findex KeyPressed
PROCEDURE KeyPressed () : BOOLEAN ;


(*
   ReadString - reads a sequence of characters.
                Tabs are expanded into 8 spaces and <cr> or <lf> terminates
                the string.
*)

@findex ReadString
PROCEDURE ReadString (VAR s: ARRAY OF CHAR) ;


(*
   ReadAgain - makes the last character readable again.
*)

@findex ReadAgain
PROCEDURE ReadAgain ;


(*
   Write - writes a single character to the Termbase module.
*)

@findex Write
PROCEDURE Write (ch: CHAR) ;


(*
   WriteString - writes out a string which is terminated by a <nul>
                 character or the end of string HIGH(s).
*)

@findex WriteString
PROCEDURE WriteString (s: ARRAY OF CHAR) ;


(*
   WriteLn - writes a lf character.
*)

@findex WriteLn
PROCEDURE WriteLn ;


END Terminal.
@end example
@page

@node gm2-libs-pim/TimeDate, , gm2-libs-pim/Terminal, PIM and Logitech 3.0 Compatible
@subsection gm2-libs-pim/TimeDate

@example
DEFINITION MODULE TimeDate ;

(*
   Legacy compatibility - you are advised to use cleaner
   designed modules based on 'man 3 strtime'
   and friends for new projects as the day value here is ugly.
   [it was mapped onto MSDOS pre 2000].
*)

EXPORT QUALIFIED Time, GetTime, SetTime, CompareTime, TimeToZero,
                 TimeToString ;

TYPE
(*
   day holds:  bits 0..4 = day of month (1..31)
                    5..8 = month of year (1..12)
                    9..  = year - 1900
   minute holds:    hours * 60 + minutes
   millisec holds:  seconds * 1000 + millisec
                    which is reset to 0 every minute
*)

   Time = RECORD
             day, minute, millisec: CARDINAL ;
          END ;


(*
   GetTime - returns the current date and time.
*)

@findex GetTime
PROCEDURE GetTime (VAR curTime: Time) ;


(*
   SetTime - does nothing, but provides compatibility with
             the Logitech-3.0 library.
*)

@findex SetTime
PROCEDURE SetTime (curTime: Time) ;


(*
   CompareTime - compare two dates and time which returns:

                 -1  if t1 < t2
                  0  if t1 = t2
                  1  if t1 > t2
*)

@findex CompareTime
PROCEDURE CompareTime (t1, t2: Time) : INTEGER ;


(*
   TimeToZero - initializes, t, to zero.
*)

@findex TimeToZero
PROCEDURE TimeToZero (VAR t: Time) ;


(*
   TimeToString - convert time, t, to a string.
                  The string, s, should be at least 19 characters
                  long and the returned string will be

                  yyyy-mm-dd hh:mm:ss
*)

@findex TimeToString
PROCEDURE TimeToString (t: Time; VAR s: ARRAY OF CHAR) ;


END TimeDate.
@end example
@page


@c ------------------------------------------------------------
@node PIM coroutine support, M2 ISO Libraries, PIM and Logitech 3.0 Compatible, Libraries
@section PIM coroutine support

@c README.texi describes the PIM coroutine libraries.
@c Copyright @copyright{} 2000-2023 Free Software Foundation, Inc.
@c
@c This is part of the GM2 manual.
@c For copying conditions, see the file gcc/doc/include/fdl.texi.

This directory contains a PIM @code{SYSTEM} containing the
@code{PROCESS} primitives built on top of @code{gthread}s.
@menu
* gm2-libs-coroutines/Debug::Debug.def
* gm2-libs-coroutines/Executive::Executive.def
* gm2-libs-coroutines/KeyBoardLEDs::KeyBoardLEDs.def
* gm2-libs-coroutines/SYSTEM::SYSTEM.def
* gm2-libs-coroutines/TimerHandler::TimerHandler.def
@end menu

@node gm2-libs-coroutines/Debug, gm2-libs-coroutines/Executive, , PIM coroutine support
@subsection gm2-libs-coroutines/Debug

@example
DEFINITION MODULE Debug ;

(*
    Description: provides some simple debugging routines.
*)

EXPORT QUALIFIED Halt, DebugString, PushOutput ;

TYPE
@findex WriteP (type)
   WriteP = PROCEDURE (CHAR) ;


(*
   Halt - writes a message in the format:
          Module:Line:Message

          It then terminates by calling HALT.
*)

@findex Halt
PROCEDURE Halt (File    : ARRAY OF CHAR;
                LineNo  : CARDINAL;
                Function,
                Message : ARRAY OF CHAR) ;


(*
   DebugString - writes a string to the debugging device (Scn.Write).
                 It interprets \n as carriage return, linefeed.
*)

@findex DebugString
PROCEDURE DebugString (a: ARRAY OF CHAR) ;


(*
   PushOutput - pushes the output procedure, p, which is used Debug.
*)

@findex PushOutput
PROCEDURE PushOutput (p: WriteP) ;


(*
   PopOutput - pops the current output procedure from the stack.
*)

@findex PopOutput
PROCEDURE PopOutput ;


END Debug.
@end example
@page

@node gm2-libs-coroutines/Executive, gm2-libs-coroutines/KeyBoardLEDs, gm2-libs-coroutines/Debug, PIM coroutine support
@subsection gm2-libs-coroutines/Executive

@example
DEFINITION MODULE Executive ;

EXPORT QUALIFIED SEMAPHORE, DESCRIPTOR,
                 InitProcess, KillProcess, Resume, Suspend, InitSemaphore,
                 Wait, Signal, WaitForIO, Ps, GetCurrentProcess,
                 RotateRunQueue, ProcessName, DebugProcess ;

TYPE
@findex SEMAPHORE (type)
   SEMAPHORE ;         (* defines Dijkstra's semaphores *)
@findex DESCRIPTOR (type)
   DESCRIPTOR ;        (* handle onto a process         *)


(*
   InitProcess - initializes a process which is held in the suspended
                 state. When the process is resumed it will start executing
                 procedure, p. The process has a maximum stack size of,
                 StackSize, bytes and its textual name is, Name.
                 The StackSize should be at least 5000 bytes.
*)

@findex InitProcess
PROCEDURE InitProcess (p: PROC; StackSize: CARDINAL;
                       Name: ARRAY OF CHAR) : DESCRIPTOR ;


(*
   KillProcess - kills the current process. Notice that if InitProcess
                 is called again, it might reuse the DESCRIPTOR of the
                 killed process. It is the responsibility of the caller
                 to ensure all other processes understand this process
                 is different.
*)

@findex KillProcess
PROCEDURE KillProcess ;


(*
   Resume - resumes a suspended process. If all is successful then the process, p,
            is returned. If it fails then NIL is returned.
*)

@findex Resume
PROCEDURE Resume (d: DESCRIPTOR) : DESCRIPTOR ;


(*
   Suspend - suspend the calling process.
             The process can only continue running if another process
             Resumes it.
*)

@findex Suspend
PROCEDURE Suspend ;


(*
   InitSemaphore - creates a semaphore whose initial value is, v, and
                   whose name is, Name.
*)

@findex InitSemaphore
PROCEDURE InitSemaphore (v: CARDINAL; Name: ARRAY OF CHAR) : SEMAPHORE ;


(*
   Wait - performs dijkstra's P operation on a semaphore.
          A process which calls this procedure will
          wait until the value of the semaphore is > 0
          and then it will decrement this value.
*)

@findex Wait
PROCEDURE Wait (s: SEMAPHORE) ;


(*
   Signal - performs dijkstra's V operation on a semaphore.
            A process which calls the procedure will increment
            the semaphores value.
*)

@findex Signal
PROCEDURE Signal (s: SEMAPHORE) ;


(*
   WaitForIO - waits for an interrupt to occur on vector, VectorNo.
*)

@findex WaitForIO
PROCEDURE WaitForIO (VectorNo: CARDINAL) ;


(*
   Ps - displays a process list together with process status.
*)

@findex Ps
PROCEDURE Ps ;


(*
   GetCurrentProcess - returns the descriptor of the current running
                       process.
*)

@findex GetCurrentProcess
PROCEDURE GetCurrentProcess () : DESCRIPTOR ;


(*
   RotateRunQueue - rotates the process run queue.
                    It does not call the scheduler.
*)

@findex RotateRunQueue
PROCEDURE RotateRunQueue ;


(*
   ProcessName - displays the name of process, d, through
                 DebugString.
*)

@findex ProcessName
PROCEDURE ProcessName (d: DESCRIPTOR) ;


(*
   DebugProcess - gdb debug handle to enable users to debug deadlocked
                  semaphore processes.
*)

@findex DebugProcess
PROCEDURE DebugProcess (d: DESCRIPTOR) ;


END Executive.
@end example
@page

@node gm2-libs-coroutines/KeyBoardLEDs, gm2-libs-coroutines/SYSTEM, gm2-libs-coroutines/Executive, PIM coroutine support
@subsection gm2-libs-coroutines/KeyBoardLEDs

@example
DEFINITION MODULE KeyBoardLEDs ;


EXPORT QUALIFIED SwitchLeds,
                 SwitchScroll, SwitchNum, SwitchCaps ;


(*
   SwitchLeds - switch the keyboard LEDs to the state defined
                by the BOOLEAN variables. TRUE = ON.
*)

@findex SwitchLeds
PROCEDURE SwitchLeds (NumLock, CapsLock, ScrollLock: BOOLEAN) ;


(*
   SwitchScroll - switchs the scroll LED on or off.
*)

@findex SwitchScroll
PROCEDURE SwitchScroll (Scroll: BOOLEAN) ;


(*
   SwitchNum - switches the Num LED on or off.
*)

@findex SwitchNum
PROCEDURE SwitchNum (Num: BOOLEAN) ;


(*
   SwitchCaps - switches the Caps LED on or off.
*)

@findex SwitchCaps
PROCEDURE SwitchCaps (Caps: BOOLEAN) ;


END KeyBoardLEDs.
@end example
@page

@node gm2-libs-coroutines/SYSTEM, gm2-libs-coroutines/TimerHandler, gm2-libs-coroutines/KeyBoardLEDs, PIM coroutine support
@subsection gm2-libs-coroutines/SYSTEM

@example
DEFINITION MODULE SYSTEM ;

(* This module is designed to be used on a native operating system
   rather than an embedded system as it implements the coroutine
   primitives TRANSFER, IOTRANSFER and
   NEWPROCESS through the GNU Pthread library.  *)

FROM COROUTINES IMPORT PROTECTION ;

EXPORT QUALIFIED (* the following are built into the compiler: *)
                 ADDRESS, WORD, BYTE, CSIZE_T, CSSIZE_T, (* 
                 Target specific data types. *)
                 ADR, TSIZE, ROTATE, SHIFT, THROW, TBITSIZE,
                 (* SIZE is exported depending upon -fpim2 and
                    -fpedantic.  *)
                 (* The rest are implemented in SYSTEM.mod.  *)
                 PROCESS, TRANSFER, NEWPROCESS, IOTRANSFER,
                 LISTEN,
                 ListenLoop, TurnInterrupts,
                 (* Internal GM2 compiler functions.  *)
                 ShiftVal, ShiftLeft, ShiftRight,
                 RotateVal, RotateLeft, RotateRight ;


TYPE
@findex PROCESS (type)
   PROCESS  = RECORD
                 context: INTEGER ;
@findex END (type)
              END ;

(* Note that the full list of system and sized datatypes include:
   LOC, WORD, BYTE, ADDRESS,

   (and the non language standard target types)

   INTEGER8, INTEGER16, INTEGER32, INTEGER64,
   CARDINAL8, CARDINAL16, CARDINAL32, CARDINAL64,
   WORD16, WORD32, WORD64, BITSET8, BITSET16,
   BITSET32, REAL32, REAL64, REAL128, COMPLEX32,
   COMPLEX64, COMPLEX128, CSIZE_T, CSSIZE_T.

   Also note that the non-standard data types will
   move into another module in the future.  *)

(* The following types are supported on this target:
   (* Target specific data types.  *)
*)


(*
   TRANSFER - save the current volatile environment into, p1.
              Restore the volatile environment from, p2.
*)

@findex TRANSFER
PROCEDURE TRANSFER (VAR p1: PROCESS; p2: PROCESS) ;


(*
   NEWPROCESS - p is a parameterless procedure, a, is the origin of
                the workspace used for the process stack and containing
                the volatile environment of the process.  StackSize, is
                the maximum size of the stack in bytes which can be used
                by this process.  new, is the new process.
*)

@findex NEWPROCESS
PROCEDURE NEWPROCESS (p: PROC; a: ADDRESS; StackSize: CARDINAL; VAR new: PROCESS) ;


(*
   IOTRANSFER - saves the current volatile environment into, First,
                and restores volatile environment, Second.
                When an interrupt, InterruptNo, is encountered then
                the reverse takes place.  (The then current volatile
                environment is shelved onto Second and First is resumed).

                NOTE: that upon interrupt the Second might not be the
                      same process as that before the original call to
                      IOTRANSFER.
*)

@findex IOTRANSFER
PROCEDURE IOTRANSFER (VAR First, Second: PROCESS; InterruptNo: CARDINAL) ;


(*
   LISTEN - briefly listen for any interrupts.
*)

@findex LISTEN
PROCEDURE LISTEN ;


(*
   ListenLoop - should be called instead of users writing:

                LOOP
                   LISTEN
                END

                It performs the same function but yields
                control back to the underlying operating system
                via a call to pth_select.
                It also checks for deadlock.
                This function returns when an interrupt occurs ie
                a file descriptor becomes ready or a time event
                expires.  See the module RTint.
*)

@findex ListenLoop
PROCEDURE ListenLoop ;


(*
   TurnInterrupts - switches processor interrupts to the protection
                    level, to.  It returns the old value.
*)

@findex TurnInterrupts
PROCEDURE TurnInterrupts (to: PROTECTION) : PROTECTION ;


(*
   all the functions below are declared internally to gm2
   ====================================================

@findex ADR
PROCEDURE ADR (VAR v: <anytype>): ADDRESS;
  (* Returns the address of variable v. *)

@findex SIZE
PROCEDURE SIZE (v: <type>) : ZType;
  (* Returns the number of BYTES used to store a v of
     any specified <type>.  Only available if -fpim2 is used.
  *)

@findex TSIZE
PROCEDURE TSIZE (<type>) : CARDINAL;
  (* Returns the number of BYTES used to store a value of the
     specified <type>.
  *)

@findex ROTATE
PROCEDURE ROTATE (val: <a set type>;
                  num: INTEGER): <type of first parameter>;
  (* Returns a bit sequence obtained from val by rotating up or down
     (left or right) by the absolute value of num.  The direction is
     down if the sign of num is negative, otherwise the direction is up.
  *)

@findex SHIFT
PROCEDURE SHIFT (val: <a set type>;
                 num: INTEGER): <type of first parameter>;
  (* Returns a bit sequence obtained from val by shifting up or down
     (left or right) by the absolute value of num, introducing
     zeros as necessary.  The direction is down if the sign of
     num is negative, otherwise the direction is up.
  *)

@findex THROW
PROCEDURE THROW (i: INTEGER) ;
  (*
     THROW is a GNU extension and was not part of the PIM or ISO
     standards.  It throws an exception which will be caught by the EXCEPT
     block (assuming it exists).  This is a compiler builtin function which
     interfaces to the GCC exception handling runtime system.
     GCC uses the term throw, hence the naming distinction between
     the GCC builtin and the Modula-2 runtime library procedure Raise.
     The later library procedure Raise will call SYSTEM.THROW after
     performing various housekeeping activities.
  *)

@findex TBITSIZE
PROCEDURE TBITSIZE (<type>) : CARDINAL ;
  (* Returns the minimum number of bits necessary to represent
     <type>.  This procedure function is only useful for determining
     the number of bits used for any type field within a packed RECORD.
     It is not particularly useful elsewhere since <type> might be
     optimized for speed, for example a BOOLEAN could occupy a WORD.
  *)
*)

(* The following procedures are invoked by GNU Modula-2 to
   shift non word sized set types.  They are not strictly part
   of the core PIM Modula-2, however they are used
   to implement the SHIFT procedure defined above,
   which are in turn used by the Logitech compatible libraries.

   Users will access these procedures by using the procedure
   SHIFT above and GNU Modula-2 will map SHIFT onto one of
   the following procedures.
*)

(*
   ShiftVal - is a runtime procedure whose job is to implement
              the SHIFT procedure of ISO SYSTEM. GNU Modula-2 will
              inline a SHIFT of a single WORD sized set and will
              only call this routine for larger sets.
*)

@findex ShiftVal
PROCEDURE ShiftVal (VAR s, d: ARRAY OF BITSET;
                    SetSizeInBits: CARDINAL;
                    ShiftCount: INTEGER) ;


(*
   ShiftLeft - performs the shift left for a multi word set.
               This procedure might be called by the back end of
               GNU Modula-2 depending whether amount is known at
               compile time.
*)

@findex ShiftLeft
PROCEDURE ShiftLeft (VAR s, d: ARRAY OF BITSET;
                     SetSizeInBits: CARDINAL;
                     ShiftCount: CARDINAL) ;

(*
   ShiftRight - performs the shift left for a multi word set.
                This procedure might be called by the back end of
                GNU Modula-2 depending whether amount is known at
                compile time.
*)

@findex ShiftRight
PROCEDURE ShiftRight (VAR s, d: ARRAY OF BITSET;
                     SetSizeInBits: CARDINAL;
                     ShiftCount: CARDINAL) ;


(*
   RotateVal - is a runtime procedure whose job is to implement
               the ROTATE procedure of ISO SYSTEM.  GNU Modula-2 will
               inline a ROTATE of a single WORD (or less)
               sized set and will only call this routine for
               larger sets.
*)

@findex RotateVal
PROCEDURE RotateVal (VAR s, d: ARRAY OF BITSET;
                     SetSizeInBits: CARDINAL;
                     RotateCount: INTEGER) ;


(*
   RotateLeft - performs the rotate left for a multi word set.
                This procedure might be called by the back end of
                GNU Modula-2 depending whether amount is known
                at compile time.
*)

@findex RotateLeft
PROCEDURE RotateLeft (VAR s, d: ARRAY OF BITSET;
                      SetSizeInBits: CARDINAL;
                      RotateCount: CARDINAL) ;


(*
   RotateRight - performs the rotate right for a multi word set.
                 This procedure might be called by the back end of
                 GNU Modula-2 depending whether amount is known at
                 compile time.
*)

@findex RotateRight
PROCEDURE RotateRight (VAR s, d: ARRAY OF BITSET;
                       SetSizeInBits: CARDINAL;
                       RotateCount: CARDINAL) ;


END SYSTEM.
@end example
@page

@node gm2-libs-coroutines/TimerHandler, , gm2-libs-coroutines/SYSTEM, PIM coroutine support
@subsection gm2-libs-coroutines/TimerHandler

@example
DEFINITION MODULE TimerHandler ;

(* It also provides the Executive with a basic round robin scheduler.  *)

EXPORT QUALIFIED TicksPerSecond, GetTicks,
                 EVENT,
                 Sleep, ArmEvent, WaitOn, Cancel, ReArmEvent ;


CONST
@findex TicksPerSecond (const)
   TicksPerSecond =   25 ;  (* Number of ticks per second.  *)

TYPE
@findex EVENT (type)
   EVENT ;


(*
   GetTicks - returns the number of ticks since boottime.
*)

@findex GetTicks
PROCEDURE GetTicks () : CARDINAL ;


(*
   Sleep - suspends the current process for a time, t.
           The time is measured in ticks.
*)

@findex Sleep
PROCEDURE Sleep (t: CARDINAL) ;


(*
   ArmEvent - initializes an event, e, to occur at time, t.
              The time, t, is measured in ticks.
              The event is NOT placed onto the event queue.
*)

@findex ArmEvent
PROCEDURE ArmEvent (t: CARDINAL) : EVENT ;


(*
   WaitOn - places event, e, onto the event queue and then the calling
            process suspends. It is resumed up by either the event
            expiring or the event, e, being cancelled.
            TRUE is returned if the event was cancelled
            FALSE is returned if the event expires.
            The event, e, is always assigned to NIL when the function
            finishes.
*)

@findex WaitOn
PROCEDURE WaitOn (VAR e: EVENT) : BOOLEAN ;


(*
   Cancel - cancels the event, e, on the event queue and makes
            the appropriate process runnable again.
            TRUE is returned if the event was cancelled and
            FALSE is returned is the event was not found or
                  no process was waiting on this event.
*)

@findex Cancel
PROCEDURE Cancel (e: EVENT) : BOOLEAN ;


(*
   ReArmEvent - removes an event, e, from the event queue. A new time
                is given to this event and it is then re-inserted onto the
                event queue in the correct place.
                TRUE is returned if this occurred
                FALSE is returned if the event was not found.
*)

@findex ReArmEvent
PROCEDURE ReArmEvent (e: EVENT; t: CARDINAL) : BOOLEAN ;


END TimerHandler.
@end example
@page


@c ------------------------------------------------------------
@node M2 ISO Libraries, , PIM coroutine support, Libraries
@section M2 ISO Libraries

@c README.texi describes the ISO libraries.
@c Copyright @copyright{} 2000-2023 Free Software Foundation, Inc.
@c
@c This is part of the GM2 manual.
@c For copying conditions, see the file gcc/doc/include/fdl.texi.

This directory contains the ISO definition modules and some
corresponding implementation modules.  The definition files:
@file{ChanConsts.def}, @file{CharClass.def}, @file{ComplexMath.def},
@file{ConvStringLong.def}, @file{ConvStringReal.def},
@file{ConvTypes.def}, @file{COROUTINES.def}, @file{EXCEPTIONS.def},
@file{GeneralUserExceptions.def}, @file{IOChan.def},
@file{IOConsts.def}, @file{IOLink.def}, @file{IOLink.def},
@file{IOResult.def}, @file{LongComplexMath.def}, @file{LongConv.def},
@file{LongIO.def}, @file{LongMath.def}, @file{LongStr.def},
@file{LowLong.def}, @file{LowReal.def}, @file{M2EXCEPTION.def},
@file{Processes.def}, @file{ProgramArgs.def}, @file{RawIO.def},
@file{RealConv.def}, @file{RealIO.def}, @file{RealMath.def},
@file{RealStr.def}, @file{RndFile.def}, @file{Semaphores.def},
@file{SeqFile.def}, @file{SIOResult.def}, @file{SLongIO.def},
@file{SRawIO.def}, @file{SRealIO.def}, @file{StdChans.def},
@file{STextIO.def}, @file{Storage.def}, @file{StreamFile.def},
@file{Strings.def}, @file{SWholeIO.def}, @file{SysClock.def},
@file{SYSTEM.def}, @file{TERMINATION.def}, @file{TextIO.def},
@file{WholeConv.def}, @file{WholeIO.def} and @file{WholeStr.def}
were defined by the International Standard
Information technology - programming languages BS ISO/IEC
10514-1:1996E Part 1: Modula-2, Base Language.

The Copyright to the definition files @file{ChanConsts.def},
@file{CharClass.def}, @file{ComplexMath.def},
@file{ConvStringLong.def}, @file{ConvStringReal.def},
@file{ConvTypes.def}, @file{COROUTINES.def}, @file{EXCEPTIONS.def},
@file{GeneralUserExceptions.def}, @file{IOChan.def},
@file{IOConsts.def}, @file{IOLink.def}, @file{IOLink.def},
@file{IOResult.def}, @file{LongComplexMath.def}, @file{LongConv.def},
@file{LongIO.def}, @file{LongMath.def}, @file{LongStr.def},
@file{LowLong.def}, @file{LowReal.def}, @file{M2EXCEPTION.def},
@file{Processes.def}, @file{ProgramArgs.def}, @file{RawIO.def},
@file{RealConv.def}, @file{RealIO.def}, @file{RealMath.def},
@file{RealStr.def}, @file{RndFile.def}, @file{Semaphores.def},
@file{SeqFile.def}, @file{SIOResult.def}, @file{SLongIO.def},
@file{SRawIO.def}, @file{SRealIO.def}, @file{StdChans.def},
@file{STextIO.def}, @file{Storage.def}, @file{StreamFile.def},
@file{Strings.def}, @file{SWholeIO.def}, @file{SysClock.def},
@file{SYSTEM.def}, @file{TERMINATION.def}, @file{TextIO.def},
@file{WholeConv.def}, @file{WholeIO.def} and @file{WholeStr.def}
belong to ISO/IEC (International Organization for Standardization and
International Electrotechnical Commission).  The licence allows them
to be distributed with the compiler (as described on page
707 of the Information technology - Programming languages Part 1:
Modula-2, Base Language.  BS ISO/IEC 10514-1:1996).

All implementation modules and @file{ClientSocket.def},
@file{LongWholeIO.def}, @file{M2RTS.def}, @file{MemStream.def},
@file{pth.def}, @file{RandomNumber.def}, @file{RTdata.def},
@file{RTentity.def}, @file{RTfio.def}, @file{RTio.def},
@file{ShortComplexMath.def}, @file{ShortIO.def},
@file{ShortWholeIO.def}, @file{SimpleCipher.def},
@file{SLongWholeIO.def}, @file{SShortIO.def},
@file{SShortWholeIO.def}, @file{StringChan.def} and
@file{wraptime.def} are Copyright of the FSF and are held under the
GPLv3 with runtime exceptions.

Under Section 7 of GPL version 3, you are granted additional
permissions described in the GCC Runtime Library Exception, version
3.1, as published by the Free Software Foundation.

You should have received a copy of the GNU General Public License and
a copy of the GCC Runtime Library Exception along with this program;
see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see
@url{http://www.gnu.org/licenses/}.

Notice that GNU Modula-2 contains additional libraries for
input/output of @code{SHORTREAL}, @code{SHORTCARD}, @code{SHORTINT},
@code{LONGCARD}, @code{LONGINT} data types.  It also provides a
@code{RandomNumber}, @code{SimpleCipher} and @code{ClientSocket}
modules as well as low level modules which allow the IO libraries to
coexist with their PIM counterparts.
@menu
* gm2-libs-iso/COROUTINES::COROUTINES.def
* gm2-libs-iso/ChanConsts::ChanConsts.def
* gm2-libs-iso/CharClass::CharClass.def
* gm2-libs-iso/ClientSocket::ClientSocket.def
* gm2-libs-iso/ComplexMath::ComplexMath.def
* gm2-libs-iso/ConvStringLong::ConvStringLong.def
* gm2-libs-iso/ConvStringReal::ConvStringReal.def
* gm2-libs-iso/ConvTypes::ConvTypes.def
* gm2-libs-iso/EXCEPTIONS::EXCEPTIONS.def
* gm2-libs-iso/ErrnoCategory::ErrnoCategory.def
* gm2-libs-iso/GeneralUserExceptions::GeneralUserExceptions.def
* gm2-libs-iso/IOChan::IOChan.def
* gm2-libs-iso/IOConsts::IOConsts.def
* gm2-libs-iso/IOLink::IOLink.def
* gm2-libs-iso/IOResult::IOResult.def
* gm2-libs-iso/LongComplexMath::LongComplexMath.def
* gm2-libs-iso/LongConv::LongConv.def
* gm2-libs-iso/LongIO::LongIO.def
* gm2-libs-iso/LongMath::LongMath.def
* gm2-libs-iso/LongStr::LongStr.def
* gm2-libs-iso/LongWholeIO::LongWholeIO.def
* gm2-libs-iso/LowLong::LowLong.def
* gm2-libs-iso/LowReal::LowReal.def
* gm2-libs-iso/LowShort::LowShort.def
* gm2-libs-iso/M2EXCEPTION::M2EXCEPTION.def
* gm2-libs-iso/M2RTS::M2RTS.def
* gm2-libs-iso/MemStream::MemStream.def
* gm2-libs-iso/Preemptive::Preemptive.def
* gm2-libs-iso/Processes::Processes.def
* gm2-libs-iso/ProgramArgs::ProgramArgs.def
* gm2-libs-iso/RTco::RTco.def
* gm2-libs-iso/RTdata::RTdata.def
* gm2-libs-iso/RTentity::RTentity.def
* gm2-libs-iso/RTfio::RTfio.def
* gm2-libs-iso/RTgen::RTgen.def
* gm2-libs-iso/RTgenif::RTgenif.def
* gm2-libs-iso/RTio::RTio.def
* gm2-libs-iso/RandomNumber::RandomNumber.def
* gm2-libs-iso/RawIO::RawIO.def
* gm2-libs-iso/RealConv::RealConv.def
* gm2-libs-iso/RealIO::RealIO.def
* gm2-libs-iso/RealMath::RealMath.def
* gm2-libs-iso/RealStr::RealStr.def
* gm2-libs-iso/RndFile::RndFile.def
* gm2-libs-iso/SIOResult::SIOResult.def
* gm2-libs-iso/SLongIO::SLongIO.def
* gm2-libs-iso/SLongWholeIO::SLongWholeIO.def
* gm2-libs-iso/SRawIO::SRawIO.def
* gm2-libs-iso/SRealIO::SRealIO.def
* gm2-libs-iso/SShortIO::SShortIO.def
* gm2-libs-iso/SShortWholeIO::SShortWholeIO.def
* gm2-libs-iso/STextIO::STextIO.def
* gm2-libs-iso/SWholeIO::SWholeIO.def
* gm2-libs-iso/SYSTEM::SYSTEM.def
* gm2-libs-iso/Semaphores::Semaphores.def
* gm2-libs-iso/SeqFile::SeqFile.def
* gm2-libs-iso/ShortComplexMath::ShortComplexMath.def
* gm2-libs-iso/ShortIO::ShortIO.def
* gm2-libs-iso/ShortWholeIO::ShortWholeIO.def
* gm2-libs-iso/SimpleCipher::SimpleCipher.def
* gm2-libs-iso/StdChans::StdChans.def
* gm2-libs-iso/Storage::Storage.def
* gm2-libs-iso/StreamFile::StreamFile.def
* gm2-libs-iso/StringChan::StringChan.def
* gm2-libs-iso/Strings::Strings.def
* gm2-libs-iso/SysClock::SysClock.def
* gm2-libs-iso/TERMINATION::TERMINATION.def
* gm2-libs-iso/TermFile::TermFile.def
* gm2-libs-iso/TextIO::TextIO.def
* gm2-libs-iso/WholeConv::WholeConv.def
* gm2-libs-iso/WholeIO::WholeIO.def
* gm2-libs-iso/WholeStr::WholeStr.def
* gm2-libs-iso/wrapsock::wrapsock.def
* gm2-libs-iso/wraptime::wraptime.def
@end menu

@node gm2-libs-iso/COROUTINES, gm2-libs-iso/ChanConsts, , M2 ISO Libraries
@subsection gm2-libs-iso/COROUTINES

@example
DEFINITION MODULE COROUTINES;

(* Facilities for coroutines and the handling of interrupts *)

IMPORT SYSTEM ;


CONST
@findex UnassignedPriority (const)
  UnassignedPriority = 0 ;

TYPE
@findex COROUTINE (type)
  COROUTINE ; (* Values of this type are created dynamically by NEWCOROUTINE
                 and identify the coroutine in subsequent operations *)
@findex INTERRUPTSOURCE (type)
  INTERRUPTSOURCE = CARDINAL ;
@findex PROTECTION (type)
  PROTECTION = [UnassignedPriority..7] ;


@findex NEWCOROUTINE
PROCEDURE NEWCOROUTINE (procBody: PROC;
                        workspace: SYSTEM.ADDRESS;
                        size: CARDINAL;
                        VAR cr: COROUTINE;
                        [initProtection: PROTECTION = UnassignedPriority]);
  (* Creates a new coroutine whose body is given by procBody, and
     returns the identity of the coroutine in cr. workspace is a
     pointer to the work space allocated to the coroutine; size
     specifies the size of this workspace in terms of SYSTEM.LOC.

     The optarg, initProtection, may contain a single parameter which
     specifies the initial protection level of the coroutine.
  *)

@findex TRANSFER
PROCEDURE TRANSFER (VAR from: COROUTINE; to: COROUTINE);
  (* Returns the identity of the calling coroutine in from, and
     transfers control to the coroutine specified by to.
  *)

@findex IOTRANSFER
PROCEDURE IOTRANSFER (VAR from: COROUTINE; to: COROUTINE);
  (* Returns the identity of the calling coroutine in from and
     transfers control to the coroutine specified by to.  On
     occurrence of an interrupt, associated with the caller, control
     is transferred back to the caller, and the identity of the
     interrupted coroutine is returned in from.  The calling coroutine
     must be associated with a source of interrupts.
  *)

@findex ATTACH
PROCEDURE ATTACH (source: INTERRUPTSOURCE);
  (* Associates the specified source of interrupts with the calling
     coroutine. *)

@findex DETACH
PROCEDURE DETACH (source: INTERRUPTSOURCE);
  (* Dissociates the specified source of interrupts from the calling
     coroutine. *)

@findex IsATTACHED
PROCEDURE IsATTACHED (source: INTERRUPTSOURCE): BOOLEAN;
  (* Returns TRUE if and only if the specified source of interrupts is
     currently associated with a coroutine; otherwise returns FALSE.
  *)

@findex HANDLER
PROCEDURE HANDLER (source: INTERRUPTSOURCE): COROUTINE;
  (* Returns the coroutine, if any, that is associated with the source
     of interrupts. The result is undefined if IsATTACHED(source) =
     FALSE.
  *)

@findex CURRENT
PROCEDURE CURRENT (): COROUTINE;
  (* Returns the identity of the calling coroutine. *)

@findex LISTEN
PROCEDURE LISTEN (p: PROTECTION);
  (* Momentarily changes the protection of the calling coroutine to
     p. *)

@findex PROT
PROCEDURE PROT (): PROTECTION;
  (* Returns the protection of the calling coroutine. *)


(*
   TurnInterrupts - switches processor interrupts to the protection
                    level, to.  It returns the old value.
*)

@findex TurnInterrupts
PROCEDURE TurnInterrupts (to: PROTECTION) : PROTECTION ;


(*
   ListenLoop - should be called instead of users writing:

                LOOP
                   LISTEN
                END

                It performs the same function but yields
                control back to the underlying operating system.
                It also checks for deadlock.
                Note that this function does return when an interrupt occurs.
                (File descriptor becomes ready or time event expires).
*)

@findex ListenLoop
PROCEDURE ListenLoop ;


END COROUTINES.
@end example
@page

@node gm2-libs-iso/ChanConsts, gm2-libs-iso/CharClass, gm2-libs-iso/COROUTINES, M2 ISO Libraries
@subsection gm2-libs-iso/ChanConsts

@example
DEFINITION MODULE ChanConsts;

  (* Common types and values for channel open requests and results *)

TYPE
@findex ChanFlags (type)
  ChanFlags =        (* Request flags possibly given when a channel is opened *)
  ( readFlag,        (* input operations are requested/available *)
    writeFlag,       (* output operations are requested/available *)
    oldFlag,         (* a file may/must/did exist before the channel is opened *)
    textFlag,        (* text operations are requested/available *)
    rawFlag,         (* raw operations are requested/available *)
    interactiveFlag, (* interactive use is requested/applies *)
    echoFlag         (* echoing by interactive device on removal of characters from input
                        stream requested/applies *)
  );

@findex FlagSet (type)
  FlagSet = SET OF ChanFlags;

  (* Singleton values of FlagSet, to allow for example, read + write *)

CONST
@findex read (const)
  read = FlagSet@{readFlag@};   (* input operations are requested/available *)
@findex write (const)
  write = FlagSet@{writeFlag@}; (* output operations are requested/available *)
@findex old (const)
  old = FlagSet@{oldFlag@};     (* a file may/must/did exist before the channel is opened *)
@findex text (const)
  text = FlagSet@{textFlag@};   (* text operations are requested/available *)
@findex raw (const)
  raw = FlagSet@{rawFlag@};     (* raw operations are requested/available *)
@findex interactive (const)
  interactive = FlagSet@{interactiveFlag@}; (* interactive use is requested/applies *)
@findex echo (const)
  echo = FlagSet@{echoFlag@};   (* echoing by interactive device on removal of characters from
                                 input stream requested/applies *)

TYPE
@findex OpenResults (type)
  OpenResults =        (* Possible results of open requests *)
    (opened,           (* the open succeeded as requested *)
     wrongNameFormat,  (* given name is in the wrong format for the implementation *)
     wrongFlags,       (* given flags include a value that does not apply to the device *)
     tooManyOpen,      (* this device cannot support any more open channels *)
     outOfChans,       (* no more channels can be allocated *)
     wrongPermissions, (* file or directory permissions do not allow request *)
     noRoomOnDevice,   (* storage limits on the device prevent the open *)
     noSuchFile,       (* a needed file does not exist *)
     fileExists,       (* a file of the given name already exists when a new one is required *)
     wrongFileType,    (* the file is of the wrong type to support the required operations *)
     noTextOperations, (* text operations have been requested, but are not supported *)
     noRawOperations,  (* raw operations have been requested, but are not supported *)
     noMixedOperations,(* text and raw operations have been requested, but they
                          are not supported in combination *)
     alreadyOpen,      (* the source/destination is already open for operations not supported
                          in combination with the requested operations *)
     otherProblem      (* open failed for some other reason *)
    );

END ChanConsts.

@end example
@page

@node gm2-libs-iso/CharClass, gm2-libs-iso/ClientSocket, gm2-libs-iso/ChanConsts, M2 ISO Libraries
@subsection gm2-libs-iso/CharClass

@example
DEFINITION MODULE CharClass;

  (* Classification of values of the type CHAR *)

@findex IsNumeric
PROCEDURE IsNumeric (ch: CHAR): BOOLEAN;
  (* Returns TRUE if and only if ch is classified as a numeric character *)

@findex IsLetter
PROCEDURE IsLetter (ch: CHAR): BOOLEAN;
  (* Returns TRUE if and only if ch is classified as a letter *)

@findex IsUpper
PROCEDURE IsUpper (ch: CHAR): BOOLEAN;
  (* Returns TRUE if and only if ch is classified as an upper case letter *)

@findex IsLower
PROCEDURE IsLower (ch: CHAR): BOOLEAN;
  (* Returns TRUE if and only if ch is classified as a lower case letter *)

@findex IsControl
PROCEDURE IsControl (ch: CHAR): BOOLEAN;
  (* Returns TRUE if and only if ch represents a control function *)

@findex IsWhiteSpace
PROCEDURE IsWhiteSpace (ch: CHAR): BOOLEAN;
  (* Returns TRUE if and only if ch represents a space character or a format effector *)

END CharClass.

@end example
@page

@node gm2-libs-iso/ClientSocket, gm2-libs-iso/ComplexMath, gm2-libs-iso/CharClass, M2 ISO Libraries
@subsection gm2-libs-iso/ClientSocket

@example
DEFINITION MODULE ClientSocket ;

FROM IOChan IMPORT ChanId ;
FROM ChanConsts IMPORT FlagSet, OpenResults ;


(*
   OpenSocket - opens a TCP client connection to host:port.
*)

@findex OpenSocket
PROCEDURE OpenSocket (VAR cid: ChanId;
                      host: ARRAY OF CHAR; port: CARDINAL;
                      f: FlagSet; VAR res: OpenResults) ;

(*
   Close - if the channel identified by cid is not open to
           a socket stream, the exception wrongDevice is
           raised; otherwise closes the channel, and assigns
           the value identifying the invalid channel to cid.
*)

@findex Close
PROCEDURE Close (VAR cid: ChanId) ;


(*
   IsSocket - tests if the channel identified by cid is open as
              a client socket stream.
*)

@findex IsSocket
PROCEDURE IsSocket (cid: ChanId) : BOOLEAN ;


END ClientSocket.
@end example
@page

@node gm2-libs-iso/ComplexMath, gm2-libs-iso/ConvStringLong, gm2-libs-iso/ClientSocket, M2 ISO Libraries
@subsection gm2-libs-iso/ComplexMath

@example
DEFINITION MODULE ComplexMath;

  (* Mathematical functions for the type COMPLEX *)

CONST
@findex i (const)
  i =    CMPLX (0.0, 1.0);
@findex one (const)
  one =  CMPLX (1.0, 0.0);
@findex zero (const)
  zero = CMPLX (0.0, 0.0);

@findex abs
PROCEDURE __BUILTIN__ abs (z: COMPLEX): REAL;
  (* Returns the length of z *)

@findex arg
PROCEDURE __BUILTIN__ arg (z: COMPLEX): REAL;
  (* Returns the angle that z subtends to the positive real axis *)

@findex conj
PROCEDURE __BUILTIN__ conj (z: COMPLEX): COMPLEX;
  (* Returns the complex conjugate of z *)

@findex power
PROCEDURE __BUILTIN__ power (base: COMPLEX; exponent: REAL): COMPLEX;
  (* Returns the value of the number base raised to the power exponent *)

@findex sqrt
PROCEDURE __BUILTIN__ sqrt (z: COMPLEX): COMPLEX;
  (* Returns the principal square root of z *)

@findex exp
PROCEDURE __BUILTIN__ exp (z: COMPLEX): COMPLEX;
  (* Returns the complex exponential of z *)

@findex ln
PROCEDURE __BUILTIN__ ln (z: COMPLEX): COMPLEX;
  (* Returns the principal value of the natural logarithm of z *)

@findex sin
PROCEDURE __BUILTIN__ sin (z: COMPLEX): COMPLEX;
  (* Returns the sine of z *)

@findex cos
PROCEDURE __BUILTIN__ cos (z: COMPLEX): COMPLEX;
  (* Returns the cosine of z *)

@findex tan
PROCEDURE __BUILTIN__ tan (z: COMPLEX): COMPLEX;
  (* Returns the tangent of z *)

@findex arcsin
PROCEDURE __BUILTIN__ arcsin (z: COMPLEX): COMPLEX;
  (* Returns the arcsine of z *)

@findex arccos
PROCEDURE __BUILTIN__ arccos (z: COMPLEX): COMPLEX;
  (* Returns the arccosine of z *)

@findex arctan
PROCEDURE __BUILTIN__ arctan (z: COMPLEX): COMPLEX;
  (* Returns the arctangent of z *)

@findex polarToComplex
PROCEDURE polarToComplex (abs, arg: REAL): COMPLEX;
  (* Returns the complex number with the specified polar coordinates *)

@findex scalarMult
PROCEDURE scalarMult (scalar: REAL; z: COMPLEX): COMPLEX;
  (* Returns the scalar product of scalar with z *)

@findex IsCMathException
PROCEDURE IsCMathException (): BOOLEAN;
  (* Returns TRUE if the current coroutine is in the exceptional
     execution state because of the raising of an exception in a
     routine from this module; otherwise returns FALSE.
  *)

END ComplexMath.

@end example
@page

@node gm2-libs-iso/ConvStringLong, gm2-libs-iso/ConvStringReal, gm2-libs-iso/ComplexMath, M2 ISO Libraries
@subsection gm2-libs-iso/ConvStringLong

@example
DEFINITION MODULE ConvStringLong ;

FROM DynamicStrings IMPORT String ;


(*
   RealToFloatString - converts a real with, sigFigs, into a string
                       and returns the result as a string.
*)

@findex RealToFloatString
PROCEDURE RealToFloatString (real: LONGREAL; sigFigs: CARDINAL) : String ;


(*
   RealToEngString - converts the value of real to floating-point
                     string form, with sigFigs significant figures.
                     The number is scaled with one to three digits
                     in the whole number part and with an exponent
                     that is a multiple of three.
*)

@findex RealToEngString
PROCEDURE RealToEngString (real: LONGREAL; sigFigs: CARDINAL) : String ;


(*
   RealToFixedString - returns the number of characters in the fixed-point
                       string representation of real rounded to the given
                       place relative to the decimal point.
*)

@findex RealToFixedString
PROCEDURE RealToFixedString (real: LONGREAL; place: INTEGER) : String ;


END ConvStringLong.
@end example
@page

@node gm2-libs-iso/ConvStringReal, gm2-libs-iso/ConvTypes, gm2-libs-iso/ConvStringLong, M2 ISO Libraries
@subsection gm2-libs-iso/ConvStringReal

@example
DEFINITION MODULE ConvStringReal ;

FROM DynamicStrings IMPORT String ;


(*
   RealToFloatString - converts a real with, sigFigs, into a string
                       and returns the result as a string.
*)

@findex RealToFloatString
PROCEDURE RealToFloatString (real: REAL; sigFigs: CARDINAL) : String ;


(*
   RealToEngString - converts the value of real to floating-point
                     string form, with sigFigs significant figures.
                     The number is scaled with one to three digits
                     in the whole number part and with an exponent
                     that is a multiple of three.
*)

@findex RealToEngString
PROCEDURE RealToEngString (real: REAL; sigFigs: CARDINAL) : String ;


(*
   RealToFixedString - returns the number of characters in the fixed-point
                       string representation of real rounded to the given
                       place relative to the decimal point.
*)

@findex RealToFixedString
PROCEDURE RealToFixedString (real: REAL; place: INTEGER) : String ;


END ConvStringReal.
@end example
@page

@node gm2-libs-iso/ConvTypes, gm2-libs-iso/EXCEPTIONS, gm2-libs-iso/ConvStringReal, M2 ISO Libraries
@subsection gm2-libs-iso/ConvTypes

@example
DEFINITION MODULE ConvTypes;

  (* Common types used in the string conversion modules *)

TYPE
@findex ConvResults (type)
  ConvResults =     (* Values of this type are used to express the format of a string *)
  (
    strAllRight,    (* the string format is correct for the corresponding conversion *)
    strOutOfRange,  (* the string is well-formed but the value cannot be represented *)
    strWrongFormat, (* the string is in the wrong format for the conversion *)
    strEmpty        (* the given string is empty *)
  );

@findex ScanClass (type)
  ScanClass =  (* Values of this type are used to classify input to finite state scanners *)
  (
    padding,   (* a leading or padding character at this point in the scan - ignore it *)
    valid,     (* a valid character at this point in the scan - accept it *)
    invalid,   (* an invalid character at this point in the scan - reject it *)
    terminator (* a terminating character at this point in the scan (not part of token) *)
  );

@findex ScanState (type)
  ScanState =  (* The type of lexical scanning control procedures *)
    PROCEDURE (CHAR, VAR ScanClass, VAR ScanState);

END ConvTypes.

@end example
@page

@node gm2-libs-iso/EXCEPTIONS, gm2-libs-iso/ErrnoCategory, gm2-libs-iso/ConvTypes, M2 ISO Libraries
@subsection gm2-libs-iso/EXCEPTIONS

@example
DEFINITION MODULE EXCEPTIONS;

(* Provides facilities for raising user exceptions
   and for making enquiries concerning the current execution state.
*)

TYPE
  ExceptionSource;   (* values of this type are used within library
                        modules to identify the source of raised
                        exceptions *)
@findex ExceptionNumber (type)
  ExceptionNumber = CARDINAL;

@findex AllocateSource
PROCEDURE AllocateSource(VAR newSource: ExceptionSource);
  (* Allocates a unique value of type ExceptionSource *)

@findex RAISE
PROCEDURE RAISE (source: ExceptionSource;
                 number: ExceptionNumber; message: ARRAY OF CHAR);
  (* Associates the given values of source, number and message with
     the current context and raises an exception.
  *)

@findex CurrentNumber
PROCEDURE CurrentNumber (source: ExceptionSource): ExceptionNumber;
  (* If the current coroutine is in the exceptional execution state
     because of the raising of an exception from source, returns
     the corresponding number, and otherwise raises an exception.
  *)

@findex GetMessage
PROCEDURE GetMessage (VAR text: ARRAY OF CHAR);
  (* If the current coroutine is in the exceptional execution state,
     returns the possibly truncated string associated with the
     current context.  Otherwise, in normal execution state,
     returns the empty string.
  *)

@findex IsCurrentSource
PROCEDURE IsCurrentSource (source: ExceptionSource): BOOLEAN;
  (* If the current coroutine is in the exceptional execution state
     because of the raising of an exception from source, returns
     TRUE, and otherwise returns FALSE.
  *)

@findex IsExceptionalExecution
PROCEDURE IsExceptionalExecution (): BOOLEAN;
  (* If the current coroutine is in the exceptional execution state
     because of the raising of an exception, returns TRUE, and
     otherwise returns FALSE.
  *)

END EXCEPTIONS.
@end example
@page

@node gm2-libs-iso/ErrnoCategory, gm2-libs-iso/GeneralUserExceptions, gm2-libs-iso/EXCEPTIONS, M2 ISO Libraries
@subsection gm2-libs-iso/ErrnoCategory

@example
DEFINITION MODULE ErrnoCategory ;

(*
   provides an interface to errno (if the system
   supports it) which determines whether the current
   errno is a hard or soft error.  These distinctions
   are needed by the ISO Modula-2 libraries.  Not all
   errno values are tested, only those which could be
   related to a device.
*)

IMPORT ChanConsts ;


(*
   IsErrnoHard - returns TRUE if the value of errno is associated with
                 a hard device error.
*)

@findex IsErrnoHard
PROCEDURE IsErrnoHard (e: INTEGER) : BOOLEAN ;


(*
   IsErrnoSoft - returns TRUE if the value of errno is associated with
                 a soft device error.
*)

@findex IsErrnoSoft
PROCEDURE IsErrnoSoft (e: INTEGER) : BOOLEAN ;


(*
   UnAvailable - returns TRUE if the value of errno indicates that
                 the resource or device is unavailable for some
                 reason.
*)

@findex UnAvailable
PROCEDURE UnAvailable (e: INTEGER) : BOOLEAN ;


(*
   GetOpenResults - maps errno onto the ISO Modula-2 enumerated
                    type, OpenResults.
*)

@findex GetOpenResults
PROCEDURE GetOpenResults (e: INTEGER) : ChanConsts.OpenResults ;


END ErrnoCategory.
@end example
@page

@node gm2-libs-iso/GeneralUserExceptions, gm2-libs-iso/IOChan, gm2-libs-iso/ErrnoCategory, M2 ISO Libraries
@subsection gm2-libs-iso/GeneralUserExceptions

@example
DEFINITION MODULE GeneralUserExceptions;

(* Provides facilities for general user-defined exceptions *)

TYPE
@findex GeneralExceptions (type)
  GeneralExceptions = (problem, disaster);

@findex RaiseGeneralException
PROCEDURE RaiseGeneralException (exception: GeneralExceptions;
                                 text: ARRAY OF CHAR);
  (* Raises exception using text as the associated message *)

@findex IsGeneralException
PROCEDURE IsGeneralException (): BOOLEAN;
  (* Returns TRUE if the current coroutine is in the exceptional
     execution state because of the raising of an exception from
     GeneralExceptions; otherwise returns FALSE.
  *)

@findex GeneralException
PROCEDURE GeneralException(): GeneralExceptions;
  (* If the current coroutine is in the exceptional execution
     state because of the raising of an exception from
     GeneralExceptions, returns the corresponding enumeration value,
     and otherwise raises an exception.
  *)

END GeneralUserExceptions.
@end example
@page

@node gm2-libs-iso/IOChan, gm2-libs-iso/IOConsts, gm2-libs-iso/GeneralUserExceptions, M2 ISO Libraries
@subsection gm2-libs-iso/IOChan

@example
DEFINITION MODULE IOChan;

  (* Types and procedures forming the interface to channels for
     device-independent data transfer modules
  *)

IMPORT IOConsts, ChanConsts, SYSTEM;

TYPE
  ChanId; (* Values of this type are used to identify channels *)

  (* There is one pre-defined value identifying an invalid channel
     on which no data transfer operations are available.  It may
     be used to initialize variables of type ChanId.
  *)

@findex InvalidChan
PROCEDURE InvalidChan (): ChanId;
  (* Returns the value identifying the invalid channel. *)

  (* For each of the following operations, if the device supports
     the operation on the channel, the behaviour of the procedure
     conforms with the description below.  The full behaviour is
     defined for each device module.  If the device does not
     support the operation on the channel, the behaviour of the
     procedure is to raise the exception notAvailable.
  *)

  (* Text operations - these perform any required translation between the
     internal and external representation of text.
  *)

@findex Look
PROCEDURE Look (cid: ChanId; VAR ch: CHAR; VAR res: IOConsts.ReadResults);
  (* If there is a character as the next item in the input stream
     cid, assigns its value to ch without removing it from the stream;
     otherwise the value of ch is not defined.  res (and the stored
     read result) are set to the value allRight, endOfLine, or endOfInput.
  *)

@findex Skip
PROCEDURE Skip (cid: ChanId);
  (* If the input stream cid has ended, the exception skipAtEnd
     is raised; otherwise the next character or line mark in cid is
     removed, and the stored read result is set to the value
     allRight.
  *)

@findex SkipLook
PROCEDURE SkipLook (cid: ChanId; VAR ch: CHAR; VAR res: IOConsts.ReadResults);
  (* If the input stream cid has ended, the exception skipAtEnd is
     raised; otherwise the next character or line mark in cid is
     removed.  If there is a character as the next item in cid
     stream, assigns its value to ch without removing it from the
     stream.  Otherwise, the value of ch is not defined.  res
     (and the stored read result) are set to the value allRight,
     endOfLine, or endOfInput.
  *)

@findex WriteLn
PROCEDURE WriteLn (cid: ChanId);
  (* Writes a line mark over the channel cid. *)

@findex TextRead
PROCEDURE TextRead (cid: ChanId; to: SYSTEM.ADDRESS; maxChars: CARDINAL;
                    VAR charsRead: CARDINAL);
  (* Reads at most maxChars characters from the current line in cid,
     and assigns corresponding values to successive components of
     an ARRAY OF CHAR variable for which the address of the first
     component is to. The number of characters read is assigned to charsRead.
     The stored read result is set to allRight, endOfLine, or endOfInput.
  *)

@findex TextWrite
PROCEDURE TextWrite (cid: ChanId; from: SYSTEM.ADDRESS;
                     charsToWrite: CARDINAL);
  (* Writes a number of characters given by the value of charsToWrite,
     from successive components of an ARRAY OF CHAR variable for which
     the address of the first component is from, to the channel cid.
  *)

  (* Direct raw operations  - these do not effect translation between
     the internal and external representation of data
  *)

@findex RawRead
PROCEDURE RawRead (cid: ChanId; to: SYSTEM.ADDRESS; maxLocs: CARDINAL;
                   VAR locsRead: CARDINAL);
  (* Reads at most maxLocs items from cid, and assigns corresponding
     values to successive components of an ARRAY OF LOC variable for
     which the address of the first component is to. The number of
     characters read is assigned to charsRead. The stored read result
     is set to the value allRight, or endOfInput.
  *)

@findex RawWrite
PROCEDURE RawWrite (cid: ChanId; from: SYSTEM.ADDRESS; locsToWrite: CARDINAL);
  (* Writes a number of items given by the value of charsToWrite,
     from successive components of an ARRAY OF LOC variable for
     which the address of the first component is from, to the channel cid.
  *)

  (* Common operations *)

@findex GetName
PROCEDURE GetName (cid: ChanId; VAR s: ARRAY OF CHAR);
  (* Copies to s a name associated with the channel cid, possibly truncated
     (depending on the capacity of s).
  *)

@findex Reset
PROCEDURE Reset (cid: ChanId);
  (* Resets the channel cid to a state defined by the device module. *)

@findex Flush
PROCEDURE Flush (cid: ChanId);
  (* Flushes any data buffered by the device module out to the channel cid. *)

  (* Access to read results *)

@findex SetReadResult
PROCEDURE SetReadResult (cid: ChanId; res: IOConsts.ReadResults);
  (* Sets the read result value for the channel cid to the value res. *)

@findex ReadResult
PROCEDURE ReadResult (cid: ChanId): IOConsts.ReadResults;
  (* Returns the stored read result value for the channel cid.
     (This is initially the value notKnown).
  *)

  (* Users can discover which flags actually apply to a channel *)

@findex CurrentFlags
PROCEDURE CurrentFlags (cid: ChanId): ChanConsts.FlagSet;
  (* Returns the set of flags that currently apply to the channel cid. *)

  (* The following exceptions are defined for this module and its clients *)

TYPE
@findex ChanExceptions (type)
  ChanExceptions =
    (wrongDevice,      (* device specific operation on wrong device *)
     notAvailable,     (* operation attempted that is not available on that
                          channel *)
     skipAtEnd,        (* attempt to skip data from a stream that has ended *)
     softDeviceError,  (* device specific recoverable error *)
     hardDeviceError,  (* device specific non-recoverable error *)
     textParseError,   (* input data does not correspond to a character or
                          line mark - optional detection *)
     notAChannel       (* given value does not identify a channel -
                          optional detection *)
    );

@findex IsChanException
PROCEDURE IsChanException (): BOOLEAN;
  (* Returns TRUE if the current coroutine is in the exceptional
     execution state because of the raising of an exception from
     ChanExceptions; otherwise returns FALSE.
  *)

@findex ChanException
PROCEDURE ChanException (): ChanExceptions;
  (* If the current coroutine is in the exceptional execution state
     because of the raising of an exception from ChanExceptions,
     returns the corresponding enumeration value, and otherwise
     raises an exception.
  *)

  (* When a device procedure detects a device error, it raises the
     exception softDeviceError or hardDeviceError.  If these
     exceptions are handled, the following facilities may be
     used to discover an implementation-defined error number for
     the channel.
  *)

TYPE
@findex DeviceErrNum (type)
  DeviceErrNum = INTEGER;

@findex DeviceError
PROCEDURE DeviceError (cid: ChanId): DeviceErrNum;
  (* If a device error exception has been raised for the channel cid,
     returns the error number stored by the device module.
  *)

END IOChan.
@end example
@page

@node gm2-libs-iso/IOConsts, gm2-libs-iso/IOLink, gm2-libs-iso/IOChan, M2 ISO Libraries
@subsection gm2-libs-iso/IOConsts

@example
DEFINITION MODULE IOConsts;

  (* Types and constants for input/output modules *)

TYPE
@findex ReadResults (type)
  ReadResults =  (* This type is used to classify the result of an input operation *)
  (
    notKnown,    (* no read result is set *)
    allRight,    (* data is as expected or as required *)
    outOfRange,  (* data cannot be represented *)
    wrongFormat, (* data not in expected format *)
    endOfLine,   (* end of line seen before expected data *)
    endOfInput   (* end of input seen before expected data *)
  );

END IOConsts.

@end example
@page

@node gm2-libs-iso/IOLink, gm2-libs-iso/IOResult, gm2-libs-iso/IOConsts, M2 ISO Libraries
@subsection gm2-libs-iso/IOLink

@example
DEFINITION MODULE IOLink;

(* Types and procedures for the standard implementation of channels *)

IMPORT IOChan, IOConsts, ChanConsts, SYSTEM;

TYPE
  DeviceId;
    (* Values of this type are used to identify new device modules,
       and are normally obtained by them during their initialization.
    *)

@findex AllocateDeviceId
PROCEDURE AllocateDeviceId (VAR did: DeviceId);
  (* Allocates a unique value of type DeviceId, and assigns this
     value to did. *)

@findex MakeChan
PROCEDURE MakeChan (did: DeviceId; VAR cid: IOChan.ChanId);
  (* Attempts to make a new channel for the device module identified
     by did. If no more channels can be made, the identity of
     the invalid channel is assigned to cid.  Otherwise, the identity
     of a new channel is assigned to cid.
  *)

@findex UnMakeChan
PROCEDURE UnMakeChan (did: DeviceId; VAR cid: IOChan.ChanId);
  (* If the device module identified by did is not the module that
     made the channel identified by cid, the exception wrongDevice is
     raised; otherwise the channel is deallocated, and the value
     identifying the invalid channel is assigned to cid.
  *)

TYPE
@findex DeviceTablePtr (type)
  DeviceTablePtr = POINTER TO DeviceTable;
    (* Values of this type are used to refer to device tables *)

TYPE
@findex LookProc (type)
  LookProc      = PROCEDURE (DeviceTablePtr, VAR CHAR, VAR IOConsts.ReadResults) ;
@findex SkipProc (type)
  SkipProc      = PROCEDURE (DeviceTablePtr) ;
@findex SkipLookProc (type)
  SkipLookProc  = PROCEDURE (DeviceTablePtr, VAR CHAR, VAR IOConsts.ReadResults) ;
@findex WriteLnProc (type)
  WriteLnProc   = PROCEDURE (DeviceTablePtr) ;
@findex TextReadProc (type)
  TextReadProc  = PROCEDURE (DeviceTablePtr, SYSTEM.ADDRESS, CARDINAL, VAR CARDINAL) ;
@findex TextWriteProc (type)
  TextWriteProc = PROCEDURE (DeviceTablePtr, SYSTEM.ADDRESS, CARDINAL) ;
@findex RawReadProc (type)
  RawReadProc   = PROCEDURE (DeviceTablePtr, SYSTEM.ADDRESS, CARDINAL, VAR CARDINAL) ;
@findex RawWriteProc (type)
  RawWriteProc  = PROCEDURE (DeviceTablePtr, SYSTEM.ADDRESS, CARDINAL) ;
@findex GetNameProc (type)
  GetNameProc   = PROCEDURE (DeviceTablePtr, VAR ARRAY OF CHAR) ;
@findex ResetProc (type)
  ResetProc     = PROCEDURE (DeviceTablePtr) ;
@findex FlushProc (type)
  FlushProc     = PROCEDURE (DeviceTablePtr) ;
@findex FreeProc (type)
  FreeProc      = PROCEDURE (DeviceTablePtr) ;
     (* Carry out the operations involved in closing the corresponding
        channel, including flushing buffers, but do not unmake the
        channel.
     *)


TYPE
@findex DeviceData (type)
  DeviceData = SYSTEM.ADDRESS;

@findex DeviceTable (type)
  DeviceTable =
    RECORD                         (* Initialized by MakeChan to: *)
      cd: DeviceData;              (* the value NIL *)
      did: DeviceId;               (* the value given in the call of MakeChan *)
      cid: IOChan.ChanId;          (* the identity of the channel *)
      result: IOConsts.ReadResults;(* the value notKnown *)
      errNum: IOChan.DeviceErrNum; (* undefined *)
      flags: ChanConsts.FlagSet;   (* ChanConsts.FlagSet@{@} *)
      doLook: LookProc;            (* raise exception notAvailable *)
      doSkip: SkipProc;            (* raise exception notAvailable *)
      doSkipLook: SkipLookProc;    (* raise exception notAvailable *)
      doLnWrite: WriteLnProc;      (* raise exception notAvailable *)
      doTextRead: TextReadProc;    (* raise exception notAvailable *)
      doTextWrite: TextWriteProc;  (* raise exception notAvailable *)
      doRawRead: RawReadProc;      (* raise exception notAvailable *)
      doRawWrite: RawWriteProc;    (* raise exception notAvailable *)
      doGetName: GetNameProc;      (* return the empty string *)
      doReset: ResetProc;          (* do nothing *)
      doFlush: FlushProc;          (* do nothing *)
      doFree: FreeProc;            (* do nothing *)
    END;


  (* The pointer to the device table for a channel is obtained using the
     following procedure: *)

(*
   If the device module identified by did is not the module that made
   the channel identified by cid, the exception wrongDevice is raised.
*)

@findex DeviceTablePtrValue
PROCEDURE DeviceTablePtrValue (cid: IOChan.ChanId; did: DeviceId): DeviceTablePtr;


(*
   Tests if the device module identified by did is the module
   that made the channel identified by cid.
*)

@findex IsDevice
PROCEDURE IsDevice (cid: IOChan.ChanId; did: DeviceId) : BOOLEAN;


TYPE
@findex DevExceptionRange (type)
  DevExceptionRange = IOChan.ChanExceptions;

(*
  ISO standard states defines

  DevExceptionRange = [IOChan.notAvailable ..  IOChan.textParseError];

  however this must be a bug as other modules need to raise
  IOChan.wrongDevice exceptions.
*)

@findex RAISEdevException
PROCEDURE RAISEdevException (cid: IOChan.ChanId; did: DeviceId;
                             x: DevExceptionRange; s: ARRAY OF CHAR);

  (* If the device module identified by did is not the module that made the channel
     identified by cid, the exception wrongDevice is raised; otherwise the given exception
     is raised, and the string value in s is included in the exception message.
  *)

@findex IsIOException
PROCEDURE IsIOException () : BOOLEAN;
  (* Returns TRUE if the current coroutine is in the exceptional execution state
     because of the raising af an exception from ChanExceptions;
     otherwise FALSE.
  *)

@findex IOException
PROCEDURE IOException () : IOChan.ChanExceptions;
  (* If the current coroutine is in the exceptional execution state because of the
     raising af an exception from ChanExceptions, returns the corresponding
     enumeration value, and otherwise raises an exception.
  *)

END IOLink.
@end example
@page

@node gm2-libs-iso/IOResult, gm2-libs-iso/LongComplexMath, gm2-libs-iso/IOLink, M2 ISO Libraries
@subsection gm2-libs-iso/IOResult

@example
DEFINITION MODULE IOResult;

  (* Read results for specified channels *)

IMPORT IOConsts, IOChan;

TYPE
@findex ReadResults (type)
  ReadResults = IOConsts.ReadResults;

  (*
@findex ReadResults (type)
    ReadResults =  (* This type is used to classify the result of an input operation *)
    (
      notKnown,    (* no read result is set *)
      allRight,    (* data is as expected or as required *)
      outOfRange,  (* data cannot be represented *)
      wrongFormat, (* data not in expected format *)
      endOfLine,   (* end of line seen before expected data *)
      endOfInput   (* end of input seen before expected data *)
    );
  *)

@findex ReadResult
PROCEDURE ReadResult (cid: IOChan.ChanId): ReadResults;
  (* Returns the result for the last read operation on the channel cid. *)

END IOResult.

@end example
@page

@node gm2-libs-iso/LongComplexMath, gm2-libs-iso/LongConv, gm2-libs-iso/IOResult, M2 ISO Libraries
@subsection gm2-libs-iso/LongComplexMath

@example
DEFINITION MODULE LongComplexMath;

  (* Mathematical functions for the type LONGCOMPLEX *)

CONST
@findex i (const)
  i =    CMPLX (0.0, 1.0);
@findex one (const)
  one =  CMPLX (1.0, 0.0);
@findex zero (const)
  zero = CMPLX (0.0, 0.0);

@findex abs
PROCEDURE abs (z: LONGCOMPLEX): LONGREAL;
  (* Returns the length of z *)

@findex arg
PROCEDURE arg (z: LONGCOMPLEX): LONGREAL;
  (* Returns the angle that z subtends to the positive real axis *)

@findex conj
PROCEDURE conj (z: LONGCOMPLEX): LONGCOMPLEX;
  (* Returns the complex conjugate of z *)

@findex power
PROCEDURE power (base: LONGCOMPLEX; exponent: LONGREAL): LONGCOMPLEX;
  (* Returns the value of the number base raised to the power exponent *)

@findex sqrt
PROCEDURE sqrt (z: LONGCOMPLEX): LONGCOMPLEX;
  (* Returns the principal square root of z *)

@findex exp
PROCEDURE exp (z: LONGCOMPLEX): LONGCOMPLEX;
  (* Returns the complex exponential of z *)

@findex ln
PROCEDURE ln (z: LONGCOMPLEX): LONGCOMPLEX;
  (* Returns the principal value of the natural logarithm of z *)

@findex sin
PROCEDURE sin (z: LONGCOMPLEX): LONGCOMPLEX;
  (* Returns the sine of z *)

@findex cos
PROCEDURE cos (z: LONGCOMPLEX): LONGCOMPLEX;
  (* Returns the cosine of z *)

@findex tan
PROCEDURE tan (z: LONGCOMPLEX): LONGCOMPLEX;
  (* Returns the tangent of z *)

@findex arcsin
PROCEDURE arcsin (z: LONGCOMPLEX): LONGCOMPLEX;
  (* Returns the arcsine of z *)

@findex arccos
PROCEDURE arccos (z: LONGCOMPLEX): LONGCOMPLEX;
  (* Returns the arccosine of z *)

@findex arctan
PROCEDURE arctan (z: LONGCOMPLEX): LONGCOMPLEX;
  (* Returns the arctangent of z *)

@findex polarToComplex
PROCEDURE polarToComplex (abs, arg: LONGREAL): LONGCOMPLEX;
  (* Returns the complex number with the specified polar coordinates *)

@findex scalarMult
PROCEDURE scalarMult (scalar: LONGREAL; z: LONGCOMPLEX): LONGCOMPLEX;
  (* Returns the scalar product of scalar with z *)

@findex IsCMathException
PROCEDURE IsCMathException (): BOOLEAN;
  (* Returns TRUE if the current coroutine is in the exceptional execution state
     because of the raising of an exception in a routine from this module; otherwise
     returns FALSE.
  *)

END LongComplexMath.

@end example
@page

@node gm2-libs-iso/LongConv, gm2-libs-iso/LongIO, gm2-libs-iso/LongComplexMath, M2 ISO Libraries
@subsection gm2-libs-iso/LongConv

@example
DEFINITION MODULE LongConv;

  (* Low-level LONGREAL/string conversions *)

IMPORT
  ConvTypes;

TYPE
@findex ConvResults (type)
  ConvResults = ConvTypes.ConvResults; (* strAllRight, strOutOfRange,
                                          strWrongFormat, strEmpty *)

@findex ScanReal
PROCEDURE ScanReal (inputCh: CHAR; VAR chClass: ConvTypes.ScanClass;
                    VAR nextState: ConvTypes.ScanState);
  (* Represents the start state of a finite state scanner for real
     numbers - assigns class of inputCh to chClass and a procedure
     representing the next state to nextState.
  *)

@findex FormatReal
PROCEDURE FormatReal (str: ARRAY OF CHAR): ConvResults;
  (* Returns the format of the string value for conversion to LONGREAL. *)

@findex ValueReal
PROCEDURE ValueReal (str: ARRAY OF CHAR): LONGREAL;
  (* Returns the value corresponding to the real number string value
     str if str is well-formed; otherwise raises the LongConv exception.
  *)

@findex LengthFloatReal
PROCEDURE LengthFloatReal (real: LONGREAL; sigFigs: CARDINAL): CARDINAL;
  (* Returns the number of characters in the floating-point string
     representation of real with sigFigs significant figures.
  *)

@findex LengthEngReal
PROCEDURE LengthEngReal (real: LONGREAL; sigFigs: CARDINAL): CARDINAL;
  (* Returns the number of characters in the floating-point engineering
     string representation of real with sigFigs significant figures.
  *)

@findex LengthFixedReal
PROCEDURE LengthFixedReal (real: LONGREAL; place: INTEGER): CARDINAL;
  (* Returns the number of characters in the fixed-point string
     representation of real rounded to the given place relative to the
     decimal point.
  *)

@findex IsRConvException
PROCEDURE IsRConvException (): BOOLEAN;
  (* Returns TRUE if the current coroutine is in the exceptional
     execution state because of the raising of an exception in a
     routine from this module; otherwise returns FALSE.
  *)

END LongConv.

@end example
@page

@node gm2-libs-iso/LongIO, gm2-libs-iso/LongMath, gm2-libs-iso/LongConv, M2 ISO Libraries
@subsection gm2-libs-iso/LongIO

@example
DEFINITION MODULE LongIO;

  (* Input and output of long real numbers in decimal text form
     over specified channels.  The read result is of the type
     IOConsts.ReadResults.
  *)

IMPORT IOChan;

  (* The text form of a signed fixed-point real number is
       ["+" | "-"], decimal digit, @{decimal digit@}, [".",
       @{decimal digit@}]

     The text form of a signed floating-point real number is
       signed fixed-point real number,
       "E", ["+" | "-"], decimal digit, @{decimal digit@}
  *)

@findex ReadReal
PROCEDURE ReadReal (cid: IOChan.ChanId; VAR real: LONGREAL);
  (* Skips leading spaces, and removes any remaining characters
     from cid that form part of a signed fixed or floating
     point number.  The value of this number is assigned to real.
     The read result is set to the value allRight, outOfRange,
     wrongFormat, endOfLine, or endOfInput.
  *)

@findex WriteFloat
PROCEDURE WriteFloat (cid: IOChan.ChanId; real: LONGREAL;
                      sigFigs: CARDINAL; width: CARDINAL);
  (* Writes the value of real to cid in floating-point text form,
     with sigFigs significant figures, in a field of the given
     minimum width.
  *)

@findex WriteEng
PROCEDURE WriteEng (cid: IOChan.ChanId; real: LONGREAL;
                    sigFigs: CARDINAL; width: CARDINAL);
  (* As for WriteFloat, except that the number is scaled with
     one to three digits in the whole number part, and with an
     exponent that is a multiple of three.
  *)

@findex WriteFixed
PROCEDURE WriteFixed (cid: IOChan.ChanId; real: LONGREAL;
                      place: INTEGER; width: CARDINAL);
  (* Writes the value of real to cid in fixed-point text form,
     rounded to the given place relative to the decimal point,
     in a field of the given minimum width.
  *)

@findex WriteReal
PROCEDURE WriteReal (cid: IOChan.ChanId; real: LONGREAL;
                     width: CARDINAL);
  (* Writes the value of real to cid, as WriteFixed if the
     sign and magnitude can be shown in the given width, or
     otherwise as WriteFloat.  The number of places or
     significant digits depends on the given width.
  *)

END LongIO.

@end example
@page

@node gm2-libs-iso/LongMath, gm2-libs-iso/LongStr, gm2-libs-iso/LongIO, M2 ISO Libraries
@subsection gm2-libs-iso/LongMath

@example
DEFINITION MODULE LongMath;

  (* Mathematical functions for the type LONGREAL *)

CONST
@findex pi (const)
  pi   = 3.1415926535897932384626433832795028841972;
@findex exp1 (const)
  exp1 = 2.7182818284590452353602874713526624977572;

@findex sqrt
PROCEDURE __BUILTIN__ sqrt (x: LONGREAL): LONGREAL;
  (* Returns the positive square root of x *)

@findex exp
PROCEDURE __BUILTIN__ exp (x: LONGREAL): LONGREAL;
  (* Returns the exponential of x *)

@findex ln
PROCEDURE __BUILTIN__ ln (x: LONGREAL): LONGREAL;
  (* Returns the natural logarithm of x *)

  (* The angle in all trigonometric functions is measured in radians *)

@findex sin
PROCEDURE __BUILTIN__ sin (x: LONGREAL): LONGREAL;
  (* Returns the sine of x *)

@findex cos
PROCEDURE __BUILTIN__ cos (x: LONGREAL): LONGREAL;
  (* Returns the cosine of x *)

@findex tan
PROCEDURE tan (x: LONGREAL): LONGREAL;
  (* Returns the tangent of x *)

@findex arcsin
PROCEDURE arcsin (x: LONGREAL): LONGREAL;
  (* Returns the arcsine of x *)

@findex arccos
PROCEDURE arccos (x: LONGREAL): LONGREAL;
  (* Returns the arccosine of x *)

@findex arctan
PROCEDURE arctan (x: LONGREAL): LONGREAL;
  (* Returns the arctangent of x *)

@findex power
PROCEDURE power (base, exponent: LONGREAL): LONGREAL;
  (* Returns the value of the number base raised to the power exponent *)

@findex round
PROCEDURE round (x: LONGREAL): INTEGER;
  (* Returns the value of x rounded to the nearest integer *)

@findex IsRMathException
PROCEDURE IsRMathException (): BOOLEAN;
  (* Returns TRUE if the current coroutine is in the exceptional
     execution state because of the raising of an exception in a
     routine from this module; otherwise returns FALSE.
  *)

END LongMath.

@end example
@page

@node gm2-libs-iso/LongStr, gm2-libs-iso/LongWholeIO, gm2-libs-iso/LongMath, M2 ISO Libraries
@subsection gm2-libs-iso/LongStr

@example
DEFINITION MODULE LongStr;

  (* LONGREAL/string conversions *)

IMPORT
   ConvTypes;

TYPE
   (* strAllRight, strOutOfRange, strWrongFormat, strEmpty *)
@findex ConvResults (type)
   ConvResults = ConvTypes.ConvResults;

(* the string form of a signed fixed-point real number is
     ["+" | "-"], decimal digit, @{decimal digit@}, [".",
     @{decimal digit@}]
*)

(* the string form of a signed floating-point real number is
     signed fixed-point real number, "E", ["+" | "-"],
     decimal digit, @{decimal digit@}
*)

@findex StrToReal
PROCEDURE StrToReal (str: ARRAY OF CHAR; VAR real: LONGREAL;
                     VAR res: ConvResults);
  (* Ignores any leading spaces in str. If the subsequent characters
     in str are in the format of a signed real number, assigns a
     corresponding value to real.  Assigns a value indicating the
     format of str to res.
  *)

@findex RealToFloat
PROCEDURE RealToFloat (real: LONGREAL; sigFigs: CARDINAL;
                       VAR str: ARRAY OF CHAR);
  (* Converts the value of real to floating-point string form, with
     sigFigs significant figures, and copies the possibly truncated
     result to str.
  *)

@findex RealToEng
PROCEDURE RealToEng (real: LONGREAL; sigFigs: CARDINAL;
                     VAR str: ARRAY OF CHAR);
  (* Converts the value of real to floating-point string form, with
     sigFigs significant figures, and copies the possibly truncated
     result to str. The number is scaled with one to three digits
     in the whole number part and with an exponent that is a
     multiple of three.
  *)

@findex RealToFixed
PROCEDURE RealToFixed (real: LONGREAL; place: INTEGER;
                       VAR str: ARRAY OF CHAR);
  (* Converts the value of real to fixed-point string form, rounded
     to the given place relative to the decimal point, and copies
     the possibly truncated result to str.
  *)

@findex RealToStr
PROCEDURE RealToStr (real: LONGREAL; VAR str: ARRAY OF CHAR);
  (* Converts the value of real as RealToFixed if the sign and
     magnitude can be shown within the capacity of str, or
     otherwise as RealToFloat, and copies the possibly truncated
     result to str. The number of places or significant digits
     depend on the capacity of str.
  *)

END LongStr.

@end example
@page

@node gm2-libs-iso/LongWholeIO, gm2-libs-iso/LowLong, gm2-libs-iso/LongStr, M2 ISO Libraries
@subsection gm2-libs-iso/LongWholeIO

@example
DEFINITION MODULE LongWholeIO;

  (* Input and output of whole numbers in decimal text form
     over specified channels.  The read result is of the
     type IOConsts.ReadResults.
  *)

IMPORT IOChan;

  (* The text form of a signed whole number is
       ["+" | "-"], decimal digit, @{decimal digit@}

     The text form of an unsigned whole number is
       decimal digit, @{decimal digit@}
  *)

@findex ReadInt
PROCEDURE ReadInt (cid: IOChan.ChanId; VAR int: LONGINT);
  (* Skips leading spaces, and removes any remaining characters
     from cid that form part of a signed whole number.  The
     value of this number is assigned to int.  The read result
     is set to the value allRight, outOfRange, wrongFormat,
     endOfLine, or endOfInput.
  *)

@findex WriteInt
PROCEDURE WriteInt (cid: IOChan.ChanId; int: LONGINT;
                    width: CARDINAL);
  (* Writes the value of int to cid in text form, in a field of
     the given minimum width. *)

@findex ReadCard
PROCEDURE ReadCard (cid: IOChan.ChanId; VAR card: LONGCARD);
  (* Skips leading spaces, and removes any remaining characters
     from cid that form part of an unsigned whole number.  The
     value of this number is assigned to card. The read result
     is set to the value allRight, outOfRange, wrongFormat,
     endOfLine, or endOfInput.
  *)

@findex WriteCard
PROCEDURE WriteCard (cid: IOChan.ChanId; card: LONGCARD;
                     width: CARDINAL);
  (* Writes the value of card to cid in text form, in a field
     of the given minimum width. *)

END LongWholeIO.
@end example
@page

@node gm2-libs-iso/LowLong, gm2-libs-iso/LowReal, gm2-libs-iso/LongWholeIO, M2 ISO Libraries
@subsection gm2-libs-iso/LowLong

@example
DEFINITION MODULE LowLong;

  (* Access to underlying properties of the type LONGREAL *)

CONST
@findex radix (const)
  radix      = __ATTRIBUTE__ __BUILTIN__ (( <LONGREAL, radix> )) ;      (* ZType *)
@findex places (const)
  places     = __ATTRIBUTE__ __BUILTIN__ (( <LONGREAL, places> )) ;     (* ZType *)
@findex expoMin (const)
  expoMin    = __ATTRIBUTE__ __BUILTIN__ (( <LONGREAL, expoMin> )) ;    (* ZType *)
@findex expoMax (const)
  expoMax    = __ATTRIBUTE__ __BUILTIN__ (( <LONGREAL, expoMax> )) ;    (* ZType *)
@findex large (const)
  large      = __ATTRIBUTE__ __BUILTIN__ (( <LONGREAL, large> )) ;      (* RType *)
@findex small (const)
  small      = __ATTRIBUTE__ __BUILTIN__ (( <LONGREAL, small> )) ;      (* RType *)
@findex IEC559 (const)
  IEC559     = __ATTRIBUTE__ __BUILTIN__ (( <LONGREAL, IEC559> )) ;     (* BOOLEAN *)
@findex LIA1 (const)
  LIA1       = __ATTRIBUTE__ __BUILTIN__ (( <LONGREAL, LIA1> )) ;       (* BOOLEAN *)
@findex ISO (const)
  ISO        = __ATTRIBUTE__ __BUILTIN__ (( <LONGREAL, ISO> )) ;        (* BOOLEAN *)
@findex IEEE (const)
  IEEE       = __ATTRIBUTE__ __BUILTIN__ (( <LONGREAL, IEEE> )) ;       (* BOOLEAN *)
@findex rounds (const)
  rounds     = __ATTRIBUTE__ __BUILTIN__ (( <LONGREAL, rounds> )) ;     (* BOOLEAN *)
@findex gUnderflow (const)
  gUnderflow = __ATTRIBUTE__ __BUILTIN__ (( <LONGREAL, gUnderflow> )) ; (* BOOLEAN *)
@findex exception (const)
  exception  = __ATTRIBUTE__ __BUILTIN__ (( <LONGREAL, exception> )) ;  (* BOOLEAN *)
@findex extend (const)
  extend     = __ATTRIBUTE__ __BUILTIN__ (( <LONGREAL, extend> )) ;     (* BOOLEAN *)
@findex nModes (const)
  nModes     = __ATTRIBUTE__ __BUILTIN__ (( <LONGREAL, nModes> )) ;     (* ZType *)

TYPE
@findex Modes (type)
  Modes = PACKEDSET OF [0 .. nModes-1];

@findex exponent
PROCEDURE exponent (x: LONGREAL): INTEGER;
  (* Returns the exponent value of x *)

@findex fraction
PROCEDURE fraction (x: LONGREAL): LONGREAL;
  (* Returns the significand (or significant part) of x *)

@findex sign
PROCEDURE sign (x: LONGREAL): LONGREAL;
  (* Returns the signum of x *)

@findex succ
PROCEDURE succ (x: LONGREAL): LONGREAL;
  (* Returns the next value of the type LONGREAL greater than x *)

@findex ulp
PROCEDURE ulp (x: LONGREAL): LONGREAL;
  (* Returns the value of a unit in the last place of x *)

@findex pred
PROCEDURE pred (x: LONGREAL): LONGREAL;
  (* Returns the previous value of the type LONGREAL less than x *)

@findex intpart
PROCEDURE intpart (x: LONGREAL): LONGREAL;
  (* Returns the integer part of x *)

@findex fractpart
PROCEDURE fractpart (x: LONGREAL): LONGREAL;
  (* Returns the fractional part of x *)

@findex scale
PROCEDURE scale (x: LONGREAL; n: INTEGER): LONGREAL;
  (* Returns the value of x * radix ** n *)

@findex trunc
PROCEDURE trunc (x: LONGREAL; n: INTEGER): LONGREAL;
  (* Returns the value of the first n places of x *)

@findex round
PROCEDURE round (x: LONGREAL; n: INTEGER): LONGREAL;
  (* Returns the value of x rounded to the first n places *)

@findex synthesize
PROCEDURE synthesize (expart: INTEGER; frapart: LONGREAL): LONGREAL;
  (* Returns a value of the type LONGREAL constructed from the given expart and frapart *)

@findex setMode
PROCEDURE setMode (m: Modes);
  (* Sets status flags appropriate to the underlying implementation of the type LONGREAL *)

@findex currentMode
PROCEDURE currentMode (): Modes;
  (* Returns the current status flags in the form set by setMode *)

@findex IsLowException
PROCEDURE IsLowException (): BOOLEAN;
  (* Returns TRUE if the current coroutine is in the exceptional execution state
     because of the raising of an exception in a routine from this module; otherwise
     returns FALSE.
  *)

END LowLong.

@end example
@page

@node gm2-libs-iso/LowReal, gm2-libs-iso/LowShort, gm2-libs-iso/LowLong, M2 ISO Libraries
@subsection gm2-libs-iso/LowReal

@example
DEFINITION MODULE LowReal;

  (* Access to underlying properties of the type REAL *)

CONST
@findex radix (const)
  radix      = __ATTRIBUTE__ __BUILTIN__ (( <REAL, radix> )) ;      (* ZType *)
@findex places (const)
  places     = __ATTRIBUTE__ __BUILTIN__ (( <REAL, places> )) ;     (* ZType *)
@findex expoMin (const)
  expoMin    = __ATTRIBUTE__ __BUILTIN__ (( <REAL, expoMin> )) ;    (* ZType *)
@findex expoMax (const)
  expoMax    = __ATTRIBUTE__ __BUILTIN__ (( <REAL, expoMax> )) ;    (* ZType *)
@findex large (const)
  large      = __ATTRIBUTE__ __BUILTIN__ (( <REAL, large> )) ;      (* RType *)
@findex small (const)
  small      = __ATTRIBUTE__ __BUILTIN__ (( <REAL, small> )) ;      (* RType *)
@findex IEC559 (const)
  IEC559     = __ATTRIBUTE__ __BUILTIN__ (( <REAL, IEC559> )) ;     (* BOOLEAN *)
@findex LIA1 (const)
  LIA1       = __ATTRIBUTE__ __BUILTIN__ (( <REAL, LIA1> )) ;       (* BOOLEAN *)
@findex ISO (const)
  ISO        = __ATTRIBUTE__ __BUILTIN__ (( <REAL, ISO> )) ;        (* BOOLEAN *)
@findex IEEE (const)
  IEEE       = __ATTRIBUTE__ __BUILTIN__ (( <REAL, IEEE> )) ;       (* BOOLEAN *)
@findex rounds (const)
  rounds     = __ATTRIBUTE__ __BUILTIN__ (( <REAL, rounds> )) ;     (* BOOLEAN *)
@findex gUnderflow (const)
  gUnderflow = __ATTRIBUTE__ __BUILTIN__ (( <REAL, gUnderflow> )) ; (* BOOLEAN *)
@findex exception (const)
  exception  = __ATTRIBUTE__ __BUILTIN__ (( <REAL, exception> )) ;  (* BOOLEAN *)
@findex extend (const)
  extend     = __ATTRIBUTE__ __BUILTIN__ (( <REAL, extend> )) ;     (* BOOLEAN *)
@findex nModes (const)
  nModes     = __ATTRIBUTE__ __BUILTIN__ (( <REAL, nModes> )) ;     (* ZType *)

TYPE
@findex Modes (type)
  Modes = PACKEDSET OF [0..nModes-1];

@findex exponent
PROCEDURE exponent (x: REAL): INTEGER;
  (* Returns the exponent value of x *)

@findex fraction
PROCEDURE fraction (x: REAL): REAL;
  (* Returns the significand (or significant part) of x *)

@findex sign
PROCEDURE sign (x: REAL): REAL;
  (* Returns the signum of x *)

@findex succ
PROCEDURE succ (x: REAL): REAL;
  (* Returns the next value of the type REAL greater than x *)

@findex ulp
PROCEDURE ulp (x: REAL): REAL;
  (* Returns the value of a unit in the last place of x *)

@findex pred
PROCEDURE pred (x: REAL): REAL;
  (* Returns the previous value of the type REAL less than x *)

@findex intpart
PROCEDURE intpart (x: REAL): REAL;
  (* Returns the integer part of x *)

@findex fractpart
PROCEDURE fractpart (x: REAL): REAL;
  (* Returns the fractional part of x *)

@findex scale
PROCEDURE scale (x: REAL; n: INTEGER): REAL;
  (* Returns the value of x * radix ** n *)

@findex trunc
PROCEDURE trunc (x: REAL; n: INTEGER): REAL;
  (* Returns the value of the first n places of x *)

@findex round
PROCEDURE round (x: REAL; n: INTEGER): REAL;
  (* Returns the value of x rounded to the first n places *)

@findex synthesize
PROCEDURE synthesize (expart: INTEGER; frapart: REAL): REAL;
  (* Returns a value of the type REAL constructed from the given expart and frapart *)

@findex setMode
PROCEDURE setMode (m: Modes);
  (* Sets status flags appropriate to the underlying implementation of the type REAL *)

@findex currentMode
PROCEDURE currentMode (): Modes;
  (* Returns the current status flags in the form set by setMode *)

@findex IsLowException
PROCEDURE IsLowException (): BOOLEAN;
  (* Returns TRUE if the current coroutine is in the exceptional execution state
     because of the raising of an exception in a routine from this module; otherwise
     returns FALSE.
  *)

END LowReal.

@end example
@page

@node gm2-libs-iso/LowShort, gm2-libs-iso/M2EXCEPTION, gm2-libs-iso/LowReal, M2 ISO Libraries
@subsection gm2-libs-iso/LowShort

@example
DEFINITION MODULE LowShort;

  (* Access to underlying properties of the type SHORTREAL *)

CONST
@findex radix (const)
  radix      = __ATTRIBUTE__ __BUILTIN__ (( <SHORTREAL, radix> )) ;      (* ZType *)
@findex places (const)
  places     = __ATTRIBUTE__ __BUILTIN__ (( <SHORTREAL, places> )) ;     (* ZType *)
@findex expoMin (const)
  expoMin    = __ATTRIBUTE__ __BUILTIN__ (( <SHORTREAL, expoMin> )) ;    (* ZType *)
@findex expoMax (const)
  expoMax    = __ATTRIBUTE__ __BUILTIN__ (( <SHORTREAL, expoMax> )) ;    (* ZType *)
@findex large (const)
  large      = __ATTRIBUTE__ __BUILTIN__ (( <SHORTREAL, large> )) ;      (* RType *)
@findex small (const)
  small      = __ATTRIBUTE__ __BUILTIN__ (( <SHORTREAL, small> )) ;      (* RType *)
@findex IEC559 (const)
  IEC559     = __ATTRIBUTE__ __BUILTIN__ (( <SHORTREAL, IEC559> )) ;     (* BOOLEAN *)
@findex LIA1 (const)
  LIA1       = __ATTRIBUTE__ __BUILTIN__ (( <SHORTREAL, LIA1> )) ;       (* BOOLEAN *)
@findex ISO (const)
  ISO        = __ATTRIBUTE__ __BUILTIN__ (( <SHORTREAL, ISO> )) ;        (* BOOLEAN *)
@findex IEEE (const)
  IEEE       = __ATTRIBUTE__ __BUILTIN__ (( <SHORTREAL, IEEE> )) ;       (* BOOLEAN *)
@findex rounds (const)
  rounds     = __ATTRIBUTE__ __BUILTIN__ (( <SHORTREAL, rounds> )) ;     (* BOOLEAN *)
@findex gUnderflow (const)
  gUnderflow = __ATTRIBUTE__ __BUILTIN__ (( <SHORTREAL, gUnderflow> )) ; (* BOOLEAN *)
@findex exception (const)
  exception  = __ATTRIBUTE__ __BUILTIN__ (( <SHORTREAL, exception> )) ;  (* BOOLEAN *)
@findex extend (const)
  extend     = __ATTRIBUTE__ __BUILTIN__ (( <SHORTREAL, extend> )) ;     (* BOOLEAN *)
@findex nModes (const)
  nModes     = __ATTRIBUTE__ __BUILTIN__ (( <SHORTREAL, nModes> )) ;     (* ZType *)

TYPE
@findex Modes (type)
  Modes = PACKEDSET OF [0 .. nModes-1];

@findex exponent
PROCEDURE exponent (x: SHORTREAL): INTEGER;
  (* Returns the exponent value of x *)

@findex fraction
PROCEDURE fraction (x: SHORTREAL): SHORTREAL;
  (* Returns the significand (or significant part) of x *)

@findex sign
PROCEDURE sign (x: SHORTREAL): SHORTREAL;
  (* Returns the signum of x *)

@findex succ
PROCEDURE succ (x: SHORTREAL): SHORTREAL;
  (* Returns the next value of the type SHORTREAL greater than x *)

@findex ulp
PROCEDURE ulp (x: SHORTREAL): SHORTREAL;
  (* Returns the value of a unit in the last place of x *)

@findex pred
PROCEDURE pred (x: SHORTREAL): SHORTREAL;
  (* Returns the previous value of the type SHORTREAL less than x *)

@findex intpart
PROCEDURE intpart (x: SHORTREAL): SHORTREAL;
  (* Returns the integer part of x *)

@findex fractpart
PROCEDURE fractpart (x: SHORTREAL): SHORTREAL;
  (* Returns the fractional part of x *)

@findex scale
PROCEDURE scale (x: SHORTREAL; n: INTEGER): SHORTREAL;
  (* Returns the value of x * radix ** n *)

@findex trunc
PROCEDURE trunc (x: SHORTREAL; n: INTEGER): SHORTREAL;
  (* Returns the value of the first n places of x *)

@findex round
PROCEDURE round (x: SHORTREAL; n: INTEGER): SHORTREAL;
  (* Returns the value of x rounded to the first n places *)

@findex synthesize
PROCEDURE synthesize (expart: INTEGER; frapart: SHORTREAL): SHORTREAL;
  (* Returns a value of the type SHORTREAL constructed from the given expart and frapart *)

@findex setMode
PROCEDURE setMode (m: Modes);
  (* Sets status flags appropriate to the underlying implementation of the type SHORTREAL *)

@findex currentMode
PROCEDURE currentMode (): Modes;
  (* Returns the current status flags in the form set by setMode *)

@findex IsLowException
PROCEDURE IsLowException (): BOOLEAN;
  (* Returns TRUE if the current coroutine is in the exceptional execution state
     because of the raising of an exception in a routine from this module; otherwise
     returns FALSE.
  *)

END LowShort.
@end example
@page

@node gm2-libs-iso/M2EXCEPTION, gm2-libs-iso/M2RTS, gm2-libs-iso/LowShort, M2 ISO Libraries
@subsection gm2-libs-iso/M2EXCEPTION

@example
DEFINITION MODULE M2EXCEPTION;

(* Provides facilities for identifying language exceptions *)

TYPE
@findex M2Exceptions (type)
  M2Exceptions =
    (indexException,     rangeException,         caseSelectException,  invalidLocation,
     functionException,  wholeValueException,    wholeDivException,    realValueException,
     realDivException,   complexValueException,  complexDivException,  protException,
     sysException,       coException,            exException
    );

@findex M2Exception
PROCEDURE M2Exception (): M2Exceptions;
  (* If the current coroutine is in the exceptional execution state because of the raising
     of a language exception, returns the corresponding enumeration value, and otherwise
     raises an exception.
  *)

@findex IsM2Exception
PROCEDURE IsM2Exception (): BOOLEAN;
  (* If the current coroutine is in the exceptional execution state because of the raising
     of a language exception, returns TRUE, and otherwise returns FALSE.
  *)

END M2EXCEPTION.
@end example
@page

@node gm2-libs-iso/M2RTS, gm2-libs-iso/MemStream, gm2-libs-iso/M2EXCEPTION, M2 ISO Libraries
@subsection gm2-libs-iso/M2RTS

@example
DEFINITION MODULE M2RTS ;

FROM SYSTEM IMPORT ADDRESS ;


TYPE
@findex ArgCVEnvP (type)
   ArgCVEnvP = PROCEDURE (INTEGER, ADDRESS, ADDRESS) ;


@findex ConstructModules
PROCEDURE ConstructModules (applicationmodule: ADDRESS;
                            argc: INTEGER; argv, envp: ADDRESS) ;

@findex DeconstructModules
PROCEDURE DeconstructModules (applicationmodule: ADDRESS;
                              argc: INTEGER; argv, envp: ADDRESS) ;


(*
   RegisterModule - adds module name to the list of outstanding
                    modules which need to have their dependencies
                    explored to determine initialization order.
*)

@findex RegisterModule
PROCEDURE RegisterModule (name: ADDRESS;
                          init, fini:  ArgCVEnvP;
                          dependencies: PROC) ;


(*
   RequestDependant - used to specify that modulename is dependant upon
                      module dependantmodule.
*)

@findex RequestDependant
PROCEDURE RequestDependant (modulename, dependantmodule: ADDRESS) ;


(*
   ExecuteTerminationProcedures - calls each installed termination
                                  procedure in reverse order.
*)

@findex ExecuteTerminationProcedures
PROCEDURE ExecuteTerminationProcedures ;


(*
   InstallTerminationProcedure - installs a procedure, p, which will
                                 be called when the procedure
                                 ExecuteTerminationProcedures
                                 is invoked.  It returns TRUE is the
                                 procedure is installed.
*)

@findex InstallTerminationProcedure
PROCEDURE InstallTerminationProcedure (p: PROC) : BOOLEAN ;


(*
   ExecuteInitialProcedures - executes the initial procedures installed
                              by InstallInitialProcedure.
*)

@findex ExecuteInitialProcedures
PROCEDURE ExecuteInitialProcedures ;


(*
   InstallInitialProcedure - installs a procedure to be executed just
                             before the BEGIN code section of the main
                             program module.
*)

@findex InstallInitialProcedure
PROCEDURE InstallInitialProcedure (p: PROC) : BOOLEAN ;


(*
   HALT - terminate the current program.  The procedure
          ExecuteTerminationProcedures
          is called before the program is stopped.  The parameter
          exitcode is optional.  If the parameter is not supplied
          HALT will call libc 'abort', otherwise it will exit with
          the code supplied.  Supplying a parameter to HALT has the
          same effect as calling ExitOnHalt with the same code and
          then calling HALT with no parameter.
*)

@findex HALT
PROCEDURE HALT ([exitcode: INTEGER = -1]) ;


(*
   Halt - provides a more user friendly version of HALT, which takes
          four parameters to aid debugging.
*)

@findex Halt
PROCEDURE Halt (file: ARRAY OF CHAR; line: CARDINAL;
                function: ARRAY OF CHAR; description: ARRAY OF CHAR) ;


(*
   ExitOnHalt - if HALT is executed then call exit with the exit code, e.
*)

@findex ExitOnHalt
PROCEDURE ExitOnHalt (e: INTEGER) ;


(*
   ErrorMessage - emits an error message to stderr and then calls exit (1).
*)

@findex ErrorMessage
PROCEDURE ErrorMessage (message: ARRAY OF CHAR;
                        file: ARRAY OF CHAR;
                        line: CARDINAL;
                        function: ARRAY OF CHAR) ;


(*
   IsTerminating - Returns true if any coroutine has started program termination
                   and false otherwise.
*)

@findex IsTerminating
PROCEDURE IsTerminating () : BOOLEAN ;


(*
   HasHalted - Returns true if a call to HALT has been made and false
               otherwise.
*)

@findex HasHalted
PROCEDURE HasHalted () : BOOLEAN ;


(*
   Length - returns the length of a string, a. This is called whenever
            the user calls LENGTH and the parameter cannot be calculated
            at compile time.
*)

@findex Length
PROCEDURE Length (a: ARRAY OF CHAR) : CARDINAL ;


(*
   The following are the runtime exception handler routines.
*)

@findex AssignmentException
PROCEDURE AssignmentException (filename: ADDRESS; line, column: CARDINAL; scope, message: ADDRESS) ;
@findex ReturnException
PROCEDURE ReturnException (filename: ADDRESS; line, column: CARDINAL; scope, message: ADDRESS) ;
@findex IncException
PROCEDURE IncException (filename: ADDRESS; line, column: CARDINAL; scope, message: ADDRESS) ;
@findex DecException
PROCEDURE DecException (filename: ADDRESS; line, column: CARDINAL; scope, message: ADDRESS) ;
@findex InclException
PROCEDURE InclException (filename: ADDRESS; line, column: CARDINAL; scope, message: ADDRESS) ;
@findex ExclException
PROCEDURE ExclException (filename: ADDRESS; line, column: CARDINAL; scope, message: ADDRESS) ;
@findex ShiftException
PROCEDURE ShiftException (filename: ADDRESS; line, column: CARDINAL; scope, message: ADDRESS) ;
@findex RotateException
PROCEDURE RotateException (filename: ADDRESS; line, column: CARDINAL; scope, message: ADDRESS) ;
@findex StaticArraySubscriptException
PROCEDURE StaticArraySubscriptException (filename: ADDRESS; line, column: CARDINAL; scope, message: ADDRESS) ;
@findex DynamicArraySubscriptException
PROCEDURE DynamicArraySubscriptException (filename: ADDRESS; line, column: CARDINAL; scope, message: ADDRESS) ;
@findex ForLoopBeginException
PROCEDURE ForLoopBeginException (filename: ADDRESS; line, column: CARDINAL; scope, message: ADDRESS) ;
@findex ForLoopToException
PROCEDURE ForLoopToException (filename: ADDRESS; line, column: CARDINAL; scope, message: ADDRESS) ;
@findex ForLoopEndException
PROCEDURE ForLoopEndException (filename: ADDRESS; line, column: CARDINAL; scope, message: ADDRESS) ;
@findex PointerNilException
PROCEDURE PointerNilException (filename: ADDRESS; line, column: CARDINAL; scope, message: ADDRESS) ;
@findex NoReturnException
PROCEDURE NoReturnException (filename: ADDRESS; line, column: CARDINAL; scope, message: ADDRESS) ;
@findex CaseException
PROCEDURE CaseException (filename: ADDRESS; line, column: CARDINAL; scope, message: ADDRESS) ;
@findex WholeNonPosDivException
PROCEDURE WholeNonPosDivException (filename: ADDRESS; line, column: CARDINAL; scope, message: ADDRESS) ;
@findex WholeNonPosModException
PROCEDURE WholeNonPosModException (filename: ADDRESS; line, column: CARDINAL; scope, message: ADDRESS) ;
@findex WholeZeroDivException
PROCEDURE WholeZeroDivException (filename: ADDRESS; line, column: CARDINAL; scope, message: ADDRESS) ;
@findex WholeZeroRemException
PROCEDURE WholeZeroRemException (filename: ADDRESS; line, column: CARDINAL; scope, message: ADDRESS) ;
@findex WholeValueException
PROCEDURE WholeValueException (filename: ADDRESS; line, column: CARDINAL; scope, message: ADDRESS) ;
@findex RealValueException
PROCEDURE RealValueException (filename: ADDRESS; line, column: CARDINAL; scope, message: ADDRESS) ;
@findex ParameterException
PROCEDURE ParameterException (filename: ADDRESS; line, column: CARDINAL; scope, message: ADDRESS) ;
@findex NoException
PROCEDURE NoException (filename: ADDRESS; line, column: CARDINAL; scope, message: ADDRESS) ;


END M2RTS.
@end example
@page

@node gm2-libs-iso/MemStream, gm2-libs-iso/Preemptive, gm2-libs-iso/M2RTS, M2 ISO Libraries
@subsection gm2-libs-iso/MemStream

@example
DEFINITION MODULE MemStream ;

(*
    Description: provides an ISO module which can write to a memory
                 buffer or read from a memory buffer.
*)

FROM IOChan IMPORT ChanId ;
FROM ChanConsts IMPORT FlagSet, OpenResults ;
FROM SYSTEM IMPORT ADDRESS, LOC ;


(*
   Attempts to obtain and open a channel connected to a contigeous
   buffer in memory.  The write flag is implied; without the raw
   flag, text is implied.  If successful, assigns to cid the identity of
   the opened channel, assigns the value opened to res.
   If a channel cannot be opened as required,
   the value of res indicates the reason, and cid identifies the
   invalid channel.

   The parameters, buffer, length and used maybe updated as
   data is written.  The buffer maybe reallocated
   and its address might alter, however the parameters will
   always reflect the current active buffer.  When this
   channel is closed the buffer is deallocated and
   buffer will be set to NIL, length and used will be set to
   zero.
*)

@findex OpenWrite
PROCEDURE OpenWrite (VAR cid: ChanId; flags: FlagSet;
                     VAR res: OpenResults;
                     VAR buffer: ADDRESS;
                     VAR length: CARDINAL;
                     VAR used: CARDINAL;
                     deallocOnClose: BOOLEAN) ;


(*
   Attempts to obtain and open a channel connected to a contigeous
   buffer in memory.  The read and old flags are implied; without
   the raw flag, text is implied.  If successful, assigns to cid the
   identity of the opened channel, assigns the value opened to res, and
   selects input mode, with the read position corresponding to the start
   of the buffer.  If a channel cannot be opened as required, the value of
   res indicates the reason, and cid identifies the invalid channel.
*)

@findex OpenRead
PROCEDURE OpenRead (VAR cid: ChanId; flags: FlagSet;
                    VAR res: OpenResults;
                    buffer: ADDRESS; length: CARDINAL;
                    deallocOnClose: BOOLEAN) ;


(*
   Close - if the channel identified by cid is not open to
           a memory stream, the exception wrongDevice is
           raised; otherwise closes the channel, and assigns
           the value identifying the invalid channel to cid.
*)

@findex Close
PROCEDURE Close (VAR cid: ChanId) ;


(*
   Rewrite - assigns the buffer index to zero.  Subsequent
             writes will overwrite the previous buffer contents.
*)

@findex Rewrite
PROCEDURE Rewrite (cid: ChanId) ;


(*
   Reread - assigns the buffer index to zero.  Subsequent
            reads will read the previous buffer contents.
*)

@findex Reread
PROCEDURE Reread (cid: ChanId) ;


(*
   IsMem - tests if the channel identified by cid is open as
           a memory stream.
*)

@findex IsMem
PROCEDURE IsMem (cid: ChanId) : BOOLEAN ;


END MemStream.
@end example
@page

@node gm2-libs-iso/Preemptive, gm2-libs-iso/Processes, gm2-libs-iso/MemStream, M2 ISO Libraries
@subsection gm2-libs-iso/Preemptive

@example
DEFINITION MODULE Preemptive ;


(*
   initPreemptive - if microsecs > 0 then turn on preemptive scheduling.
                    if microsecs = 0 then preemptive scheduling is turned off.
*)

@findex initPreemptive
PROCEDURE initPreemptive (seconds, microsecs: CARDINAL) ;


END Preemptive.
@end example
@page

@node gm2-libs-iso/Processes, gm2-libs-iso/ProgramArgs, gm2-libs-iso/Preemptive, M2 ISO Libraries
@subsection gm2-libs-iso/Processes

@example
DEFINITION MODULE Processes;

  (* This module allows concurrent algorithms to be expressed using
     processes. A process is a unit of a program that has the
     potential to run in parallel with other processes.
  *)

IMPORT SYSTEM;

TYPE
  ProcessId;                      (* Used to identify processes *)
@findex Parameter (type)
  Parameter     = SYSTEM.ADDRESS; (* Used to pass data between processes *)
@findex Body (type)
  Body          = PROC;           (* Used as the type of a process body *)
@findex Urgency (type)
  Urgency       = INTEGER;        (* Used by the internal scheduler *)
@findex Sources (type)
  Sources       = CARDINAL;       (* Used to identify event sources *)
@findex ProcessesExceptions (type)
  ProcessesExceptions =           (* Exceptions raised by this module *)
    (passiveProgram, processError);

(* The following procedures create processes and switch control between
   them. *)

@findex Create
PROCEDURE Create (procBody: Body; extraSpace: CARDINAL; procUrg: Urgency;
                  procParams: Parameter; VAR procId: ProcessId);
  (* Creates a new process with procBody as its body, and with urgency
     and parameters given by procUrg and procParams.  At least as
     much workspace (in units of SYSTEM.LOC) as is specified by
     extraSpace is allocated to the process.
     An identity for the new process is returned in procId.
     The process is created in the passive state; it will not run
     until activated.
  *)

@findex Start
PROCEDURE Start (procBody: Body; extraSpace: CARDINAL; procUrg: Urgency;
                 procParams: Parameter; VAR procId: ProcessId);
  (* Creates a new process, with parameters as for Create.
     The process is created in the ready state; it is eligible to
     run immediately.
  *)

@findex StopMe
PROCEDURE StopMe ();
  (* Terminates the calling process.
     The process must not be associated with a source of events.
  *)

@findex SuspendMe
PROCEDURE SuspendMe ();
  (* Causes the calling process to enter the passive state.  The
     procedure only returns when the calling process is again
     activated by another process.
  *)

@findex Activate
PROCEDURE Activate (procId: ProcessId);
  (* Causes the process identified by procId to enter the ready
     state, and thus to become eligible to run again.
  *)

@findex SuspendMeAndActivate
PROCEDURE SuspendMeAndActivate (procId: ProcessId);
  (* Executes an atomic sequence of SuspendMe() and
     Activate(procId). *)

@findex Switch
PROCEDURE Switch (procId: ProcessId; VAR info: Parameter);
  (* Causes the calling process to enter the passive state; the
     process identified by procId becomes the currently executing
     process.  info is used to pass parameter information from the
     calling to the activated process.  On return, info will
     contain information from the process that chooses to switch
     back to this one (or will be NIL if Activate or
     SuspendMeAndActivate are used instead of Switch).
  *)

@findex Wait
PROCEDURE Wait ();
  (* Causes the calling process to enter the waiting state.
     The procedure will return when the calling process is
     activated by another process, or when one of its associated
     eventSources has generated an event.
  *)

(* The following procedures allow the association of processes
   with sources of external events.
*)

@findex Attach
PROCEDURE Attach (eventSource: Sources);
  (* Associates the specified eventSource with the calling
     process. *)

@findex Detach
PROCEDURE Detach (eventSource: Sources);
  (* Dissociates the specified eventSource from the program. *)

@findex IsAttached
PROCEDURE IsAttached (eventSource: Sources): BOOLEAN;
  (* Returns TRUE if and only if the specified eventSource is
     currently associated with one of the processes of the
     program.
  *)

@findex Handler
PROCEDURE Handler (eventSource: Sources): ProcessId;
  (* Returns the identity of the process, if any, that is
     associated with the specified eventSource.
  *)

(* The following procedures allow processes to obtain their
   identity, parameters, and urgency.
*)

@findex Me
PROCEDURE Me (): ProcessId;
  (* Returns the identity of the calling process (as assigned
     when the process was first created).
  *)

@findex MyParam
PROCEDURE MyParam (): Parameter;
  (* Returns the value specified as procParams when the calling
     process was created. *)

@findex UrgencyOf
PROCEDURE UrgencyOf (procId: ProcessId): Urgency;
  (* Returns the urgency established when the process identified
     by procId was first created.
  *)

(* The following procedure provides facilities for exception
   handlers. *)

@findex ProcessesException
PROCEDURE ProcessesException (): ProcessesExceptions;
  (* If the current coroutine is in the exceptional execution state
     because of the raising of a language exception, returns the
     corresponding enumeration value, and otherwise raises an
     exception.
  *)

@findex IsProcessesException
PROCEDURE IsProcessesException (): BOOLEAN;
  (* Returns TRUE if the current coroutine is in the exceptional
     execution state because of the raising of an exception in
     a routine from this module; otherwise returns FALSE.
  *)

(*
   Reschedule - rotates the ready queue and transfers to the process
                with the highest run priority.
*)

@findex Reschedule
PROCEDURE Reschedule ;


(*
   displayProcesses -
*)

@findex displayProcesses
PROCEDURE displayProcesses (message: ARRAY OF CHAR) ;


END Processes.
@end example
@page

@node gm2-libs-iso/ProgramArgs, gm2-libs-iso/RTco, gm2-libs-iso/Processes, M2 ISO Libraries
@subsection gm2-libs-iso/ProgramArgs

@example
DEFINITION MODULE ProgramArgs;

  (* Access to program arguments *)

IMPORT IOChan;

TYPE
@findex ChanId (type)
  ChanId = IOChan.ChanId;

@findex ArgChan
PROCEDURE ArgChan (): ChanId;
  (* Returns a value that identifies a channel for reading
     program arguments *)

@findex IsArgPresent
PROCEDURE IsArgPresent (): BOOLEAN;
  (* Tests if there is a current argument to read from.  If not,
     read <= IOChan.CurrentFlags() will be FALSE, and attempting
     to read from the argument channel will raise the exception
     notAvailable.
  *)

@findex NextArg
PROCEDURE NextArg ();
  (* If there is another argument, causes subsequent input from the
     argument device to come from the start of the next argument.
     Otherwise there is no argument to read from, and a call of
     IsArgPresent will return FALSE.
  *)

END ProgramArgs.
@end example
@page

@node gm2-libs-iso/RTco, gm2-libs-iso/RTdata, gm2-libs-iso/ProgramArgs, M2 ISO Libraries
@subsection gm2-libs-iso/RTco

@example
DEFINITION MODULE RTco ;

FROM SYSTEM IMPORT ADDRESS ;


(* init initializes the module and allows the application to lazily invoke threads.  *)

@findex init
PROCEDURE init () : INTEGER ;

@findex initThread
PROCEDURE initThread (p: PROC; stackSize: CARDINAL; interruptLevel: CARDINAL) : INTEGER ;

@findex initSemaphore
PROCEDURE initSemaphore (value: CARDINAL) : INTEGER ;

@findex wait
PROCEDURE wait (semaphore: INTEGER) ;

@findex signal
PROCEDURE signal (semaphore: INTEGER) ;

@findex transfer
PROCEDURE transfer (VAR p1: INTEGER; p2: INTEGER) ;

@findex waitThread
PROCEDURE waitThread (tid: INTEGER) ;

@findex signalThread
PROCEDURE signalThread (tid: INTEGER) ;

@findex currentThread
PROCEDURE currentThread () : INTEGER ;


(* currentInterruptLevel returns the interrupt level of the current thread.  *)

@findex currentInterruptLevel
PROCEDURE currentInterruptLevel () : CARDINAL ;


(* turninterrupts returns the old interrupt level and assigns the interrupt level
   to newLevel.  *)

@findex turnInterrupts
PROCEDURE turnInterrupts (newLevel: CARDINAL) : CARDINAL ;


(*
   select access to the select system call which will be thread safe.
   This is typically called from the idle process to wait for an interrupt.
*)

@findex select
PROCEDURE select (p1: INTEGER;
                  p2: ADDRESS;
                  p3: ADDRESS;
                  p4: ADDRESS;
                  p5: ADDRESS) : INTEGER ;


END RTco.
@end example
@page

@node gm2-libs-iso/RTdata, gm2-libs-iso/RTentity, gm2-libs-iso/RTco, M2 ISO Libraries
@subsection gm2-libs-iso/RTdata

@example
DEFINITION MODULE RTdata ;

(*
    Description: provides a mechanism whereby devices can store
                 data attached to a device.
*)

FROM SYSTEM IMPORT ADDRESS ;
FROM IOLink IMPORT DeviceTablePtr ;

TYPE
@findex ModuleId (type)
   ModuleId ;
@findex FreeProcedure (type)
   FreeProcedure = PROCEDURE (ADDRESS) ;


(*
   MakeModuleId - creates a unique module Id.
*)

@findex MakeModuleId
PROCEDURE MakeModuleId (VAR m: ModuleId) ;


(*
   InitData - adds, datum, to the device, d.  The datum
              is associated with ModuleID, m.
*)

@findex InitData
PROCEDURE InitData (d: DeviceTablePtr; m: ModuleId;
                    datum: ADDRESS; f: FreeProcedure) ;


(*
   GetData - returns the datum assocated with ModuleId, m.
*)

@findex GetData
PROCEDURE GetData (d: DeviceTablePtr; m: ModuleId) : ADDRESS ;


(*
   KillData - destroys the datum associated with ModuleId, m,
              in device, d.  It invokes the free procedure
              given during InitData.
*)

@findex KillData
PROCEDURE KillData (d: DeviceTablePtr; m: ModuleId) ;


END RTdata.
@end example
@page

@node gm2-libs-iso/RTentity, gm2-libs-iso/RTfio, gm2-libs-iso/RTdata, M2 ISO Libraries
@subsection gm2-libs-iso/RTentity

@example
DEFINITION MODULE RTentity ;

(*
    Description: provides a set of routines for maintaining an
                 efficient mechanism to group opaque (or pointer)
                 data structures together.  Internally the
                 entities are grouped together using a binary
                 tree.  It does not use Storage - and instead
                 uses malloc, free from libc as Storage uses the
                 module to detect erroneous deallocations.
*)

IMPORT SYSTEM ;

TYPE
@findex Group (type)
   Group ;


@findex InitGroup
PROCEDURE InitGroup () : Group ;
@findex KillGroup
PROCEDURE KillGroup (g: Group) : Group ;
@findex GetKey
PROCEDURE GetKey (g: Group; a: SYSTEM.ADDRESS) : CARDINAL ;
@findex PutKey
PROCEDURE PutKey (g: Group; a: SYSTEM.ADDRESS; key: CARDINAL) ;
@findex DelKey
PROCEDURE DelKey (g: Group; a: SYSTEM.ADDRESS) ;
@findex IsIn
PROCEDURE IsIn (g: Group; a: SYSTEM.ADDRESS) : BOOLEAN ;


END RTentity.
@end example
@page

@node gm2-libs-iso/RTfio, gm2-libs-iso/RTgen, gm2-libs-iso/RTentity, M2 ISO Libraries
@subsection gm2-libs-iso/RTfio

@example
DEFINITION MODULE RTfio ;

(*
    Description: provides default FIO based methods for the RTgenif
                 procedures.  These will be used by StreamFile,
                 SeqFile, StdChans, TermFile and RndFile.
*)

FROM SYSTEM IMPORT ADDRESS ;
FROM IOLink IMPORT DeviceTablePtr;
FROM RTgenif IMPORT GenDevIF ;


(*
   doreadchar - returns a CHAR from the file associated with, g.
*)

@findex doreadchar
PROCEDURE doreadchar (g: GenDevIF; d: DeviceTablePtr) : CHAR ;


(*
   dounreadchar - pushes a CHAR back onto the file associated
                  with, g.
*)

@findex dounreadchar
PROCEDURE dounreadchar (g: GenDevIF; d: DeviceTablePtr; ch: CHAR) : CHAR ;


(*
   dogeterrno - returns the errno relating to the generic device.
*)

@findex dogeterrno
PROCEDURE dogeterrno (g: GenDevIF; d: DeviceTablePtr) : INTEGER ;


(*
   dorbytes - reads upto, max, bytes setting, actual, and
              returning FALSE if an error (not due to eof)
              occurred.
*)

@findex dorbytes
PROCEDURE dorbytes (g: GenDevIF;
                    d: DeviceTablePtr;
                    to: ADDRESS;
                    max: CARDINAL;
                    VAR actual: CARDINAL) : BOOLEAN ;

(*
   dowbytes - writes up to, nBytes.  It returns FALSE
              if an error occurred and it sets actual
              to the amount of data written.
*)

@findex dowbytes
PROCEDURE dowbytes (g: GenDevIF;
                    d: DeviceTablePtr;
                    from: ADDRESS;
                    nBytes: CARDINAL;
                    VAR actual: CARDINAL) : BOOLEAN ;


(*
   dowriteln - attempt to write an end of line marker to the
               file and returns TRUE if successful.
*)

@findex dowriteln
PROCEDURE dowriteln (g: GenDevIF; d: DeviceTablePtr) : BOOLEAN ;


(*
   iseof - returns TRUE if end of file has been seen.
*)

@findex iseof
PROCEDURE iseof (g: GenDevIF; d: DeviceTablePtr) : BOOLEAN ;


(*
   iseoln - returns TRUE if end of line has been seen.
*)

@findex iseoln
PROCEDURE iseoln (g: GenDevIF; d: DeviceTablePtr) : BOOLEAN ;


(*
   iserror - returns TRUE if an error was seen on the device.
             Note that reaching EOF is not classified as an
             error.
*)

@findex iserror
PROCEDURE iserror (g: GenDevIF; d: DeviceTablePtr) : BOOLEAN ;


END RTfio.
@end example
@page

@node gm2-libs-iso/RTgen, gm2-libs-iso/RTgenif, gm2-libs-iso/RTfio, M2 ISO Libraries
@subsection gm2-libs-iso/RTgen

@example
DEFINITION MODULE RTgen ;

(*
    Description: provides a generic device interface between
                 ISO channels and the underlying PIM style
                 FIO procedure calls.
*)

FROM RTgenif IMPORT GenDevIF ;
FROM IOLink IMPORT DeviceId, DeviceTablePtr;
FROM IOConsts IMPORT ReadResults ;
FROM SYSTEM IMPORT ADDRESS ;


TYPE
@findex ChanDev (type)
   ChanDev ;
@findex DeviceType (type)
   DeviceType = (seqfile, streamfile, programargs, stdchans, term, socket, rndfile) ;


(*
   InitChanDev - initialize and return a ChanDev.
*)

@findex InitChanDev
PROCEDURE InitChanDev (t: DeviceType; d: DeviceId; g: GenDevIF) : ChanDev ;


(*
   KillChanDev - deallocates, g.
*)

@findex KillChanDev
PROCEDURE KillChanDev (g: GenDevIF) : GenDevIF ;


(*
   RaiseEOFinLook - returns TRUE if the Look procedure
                    should raise an exception if it
                    sees end of file.
*)

@findex RaiseEOFinLook
PROCEDURE RaiseEOFinLook (g: ChanDev) : BOOLEAN ;


(*
   RaiseEOFinSkip - returns TRUE if the Skip procedure
                    should raise an exception if it
                    sees end of file.
*)

@findex RaiseEOFinSkip
PROCEDURE RaiseEOFinSkip (g: ChanDev) : BOOLEAN ;


@findex doLook
PROCEDURE doLook (g: ChanDev;
                  d: DeviceTablePtr;
                  VAR ch: CHAR;
                  VAR r: ReadResults) ;

@findex doSkip
PROCEDURE doSkip (g: ChanDev;
                  d: DeviceTablePtr) ;

@findex doSkipLook
PROCEDURE doSkipLook (g: ChanDev;
                      d: DeviceTablePtr;
                      VAR ch: CHAR;
                      VAR r: ReadResults) ;

@findex doWriteLn
PROCEDURE doWriteLn (g: ChanDev;
                     d: DeviceTablePtr) ;

@findex doReadText
PROCEDURE doReadText (g: ChanDev;
                      d: DeviceTablePtr;
                      to: ADDRESS;
                      maxChars: CARDINAL;
                      VAR charsRead: CARDINAL) ;

@findex doWriteText
PROCEDURE doWriteText (g: ChanDev;
                       d: DeviceTablePtr;
                       from: ADDRESS;
                       charsToWrite: CARDINAL) ;

@findex doReadLocs
PROCEDURE doReadLocs (g: ChanDev;
                      d: DeviceTablePtr;
                      to: ADDRESS;
                      maxLocs: CARDINAL;
                      VAR locsRead: CARDINAL) ;

@findex doWriteLocs
PROCEDURE doWriteLocs (g: ChanDev;
                       d: DeviceTablePtr;
                       from: ADDRESS;
                       locsToWrite: CARDINAL) ;

(*
   checkErrno - checks a number of errno conditions and raises
                appropriate ISO exceptions if they occur.
*)

@findex checkErrno
PROCEDURE checkErrno (g: ChanDev; d: DeviceTablePtr) ;


END RTgen.
@end example
@page

@node gm2-libs-iso/RTgenif, gm2-libs-iso/RTio, gm2-libs-iso/RTgen, M2 ISO Libraries
@subsection gm2-libs-iso/RTgenif

@example
DEFINITION MODULE RTgenif ;

(*
    Description: provides a generic interface mechanism used
                 by RTgen.  This is not an ISO module but rather
                 a runtime support module.
*)

FROM SYSTEM IMPORT ADDRESS ;
FROM IOLink IMPORT DeviceId, DeviceTablePtr ;

TYPE
@findex GenDevIF (type)
   GenDevIF ;
@findex readchar (type)
   readchar   = PROCEDURE (GenDevIF, DeviceTablePtr) : CHAR ;
@findex unreadchar (type)
   unreadchar = PROCEDURE (GenDevIF, DeviceTablePtr, CHAR) : CHAR ;
@findex geterrno (type)
   geterrno   = PROCEDURE (GenDevIF, DeviceTablePtr) : INTEGER ;
@findex readbytes (type)
   readbytes  = PROCEDURE (GenDevIF, DeviceTablePtr, ADDRESS, CARDINAL, VAR CARDINAL) : BOOLEAN ;
@findex writebytes (type)
   writebytes = PROCEDURE (GenDevIF, DeviceTablePtr, ADDRESS, CARDINAL, VAR CARDINAL) : BOOLEAN ;
@findex writeln (type)
   writeln    = PROCEDURE (GenDevIF, DeviceTablePtr) : BOOLEAN ;
@findex iseof (type)
   iseof      = PROCEDURE (GenDevIF, DeviceTablePtr) : BOOLEAN ;
@findex iseoln (type)
   iseoln     = PROCEDURE (GenDevIF, DeviceTablePtr) : BOOLEAN ;
@findex iserror (type)
   iserror    = PROCEDURE (GenDevIF, DeviceTablePtr) : BOOLEAN ;


(*
   InitGenDevIF - initializes a generic device.
*)

@findex InitGenDevIF
PROCEDURE InitGenDevIF (d     : DeviceId;
                        rc    : readchar;
                        urc   : unreadchar;
                        geterr: geterrno;
                        rbytes: readbytes;
                        wbytes: writebytes;
                        wl    : writeln;
                        eof   : iseof;
                        eoln  : iseoln;
                        iserr : iserror) : GenDevIF ;


(*
   getDID - returns the device id this generic interface.
*)

@findex getDID
PROCEDURE getDID (g: GenDevIF) : DeviceId ;


(*
   doReadChar - returns the next character from the generic
                device.
*)

@findex doReadChar
PROCEDURE doReadChar (g: GenDevIF; d: DeviceTablePtr) : CHAR ;


(*
   doUnReadChar - pushes back a character to the generic device.
*)

@findex doUnReadChar
PROCEDURE doUnReadChar (g: GenDevIF; d: DeviceTablePtr; ch: CHAR) : CHAR ;


(*
   doGetErrno - returns the errno relating to the generic device.
*)

@findex doGetErrno
PROCEDURE doGetErrno (g: GenDevIF; d: DeviceTablePtr) : INTEGER ;


(*
   doRBytes - attempts to read, n, bytes from the generic device.
              It set the actual amount read and returns a boolean
              to determine whether an error occurred.
*)

@findex doRBytes
PROCEDURE doRBytes (g: GenDevIF; d: DeviceTablePtr;
                    to: ADDRESS; max: CARDINAL;
                    VAR actual: CARDINAL) : BOOLEAN ;


(*
   doWBytes - attempts to write, n, bytes to the generic device.
              It sets the actual amount written and returns a
              boolean to determine whether an error occurred.
*)

@findex doWBytes
PROCEDURE doWBytes (g: GenDevIF; d: DeviceTablePtr;
                    from: ADDRESS; max: CARDINAL;
                    VAR actual: CARDINAL) : BOOLEAN ;


(*
   doWrLn - writes an end of line marker and returns
            TRUE if successful.
*)

@findex doWrLn
PROCEDURE doWrLn (g: GenDevIF; d: DeviceTablePtr) : BOOLEAN ;


(*
   isEOF - returns true if the end of file was reached.
*)

@findex isEOF
PROCEDURE isEOF (g: GenDevIF; d: DeviceTablePtr) : BOOLEAN ;


(*
   isEOLN - returns true if the end of line was reached.
*)

@findex isEOLN
PROCEDURE isEOLN (g: GenDevIF; d: DeviceTablePtr) : BOOLEAN ;


(*
   isError - returns true if an error was seen in the device.
*)

@findex isError
PROCEDURE isError (g: GenDevIF; d: DeviceTablePtr) : BOOLEAN ;


(*
   KillGenDevIF - deallocates a generic device.
*)

@findex KillGenDevIF
PROCEDURE KillGenDevIF (g: GenDevIF) : GenDevIF ;


END RTgenif.
@end example
@page

@node gm2-libs-iso/RTio, gm2-libs-iso/RandomNumber, gm2-libs-iso/RTgenif, M2 ISO Libraries
@subsection gm2-libs-iso/RTio

@example
DEFINITION MODULE RTio ;

(*
    Description: provides low level routines for creating and destroying
                 ChanIds.  This is necessary to allow multiple modules
                 to create, ChanId values, where ChanId is an opaque
                 type.
*)

IMPORT FIO, IOLink ;

TYPE
@findex ChanId (type)
   ChanId ;


(*
   InitChanId - return a new ChanId.
*)

@findex InitChanId
PROCEDURE InitChanId () : ChanId ;


(*
   KillChanId - deallocate a ChanId.
*)

@findex KillChanId
PROCEDURE KillChanId (c: ChanId) : ChanId ;


(*
   NilChanId - return a NIL pointer.
*)

@findex NilChanId
PROCEDURE NilChanId () : ChanId ;


(*
   GetDeviceId - returns the device id, from, c.
*)

@findex GetDeviceId
PROCEDURE GetDeviceId (c: ChanId) : IOLink.DeviceId ;


(*
   SetDeviceId - sets the device id in, c.
*)

@findex SetDeviceId
PROCEDURE SetDeviceId (c: ChanId; d: IOLink.DeviceId) ;


(*
   GetDevicePtr - returns the device table ptr, from, c.
*)

@findex GetDevicePtr
PROCEDURE GetDevicePtr (c: ChanId) : IOLink.DeviceTablePtr ;


(*
   SetDevicePtr - sets the device table ptr in, c.
*)

@findex SetDevicePtr
PROCEDURE SetDevicePtr (c: ChanId; p: IOLink.DeviceTablePtr) ;


(*
   GetFile - returns the file field from, c.
*)

@findex GetFile
PROCEDURE GetFile (c: ChanId) : FIO.File ;


(*
   SetFile - sets the file field in, c.
*)

@findex SetFile
PROCEDURE SetFile (c: ChanId; f: FIO.File) ;


END RTio.
@end example
@page

@node gm2-libs-iso/RandomNumber, gm2-libs-iso/RawIO, gm2-libs-iso/RTio, M2 ISO Libraries
@subsection gm2-libs-iso/RandomNumber

@example
DEFINITION MODULE RandomNumber ;

(*
    Description: provides primitives for obtaining random numbers on
                 pervasive data types.
*)

FROM SYSTEM IMPORT BYTE ;
EXPORT QUALIFIED Randomize, RandomInit, RandomBytes,
                 RandomCard, RandomShortCard, RandomLongCard,
                 RandomInt, RandomShortInt, RandomLongInt,
                 RandomReal, RandomLongReal, RandomShortReal ;


(*
   Randomize - initialize the random number generator with a seed
               based on the microseconds.
*)

@findex Randomize
PROCEDURE Randomize ;


(*
   RandomInit - initialize the random number generator with value, seed.
*)

@findex RandomInit
PROCEDURE RandomInit (seed: CARDINAL) ;


(*
   RandomBytes - fills in an array with random values.
*)

@findex RandomBytes
PROCEDURE RandomBytes (VAR a: ARRAY OF BYTE) ;


(*
   RandomInt - return an INTEGER in the range [low .. high].
*)

@findex RandomInt
PROCEDURE RandomInt (low, high: INTEGER) : INTEGER ;


(*
   RandomShortInt - return an SHORTINT in the range [low..high].
*)

@findex RandomShortInt
PROCEDURE RandomShortInt (low, high: SHORTINT) : SHORTINT ;


(*
   RandomLongInt - return an LONGINT in the range [low..high].
*)

@findex RandomLongInt
PROCEDURE RandomLongInt (low, high: LONGINT) : LONGINT ;


(*
   RandomShortCard - return a SHORTCARD in the range [low..high].
*)

@findex RandomShortCard
PROCEDURE RandomShortCard (low, high: CARDINAL) : CARDINAL ;


(*
   RandomCard - return a CARDINAL in the range [low..high].
*)

@findex RandomCard
PROCEDURE RandomCard (low, high: CARDINAL) : CARDINAL ;


(*
   RandomLongCard - return an LONGCARD in the range [low..high].
*)

@findex RandomLongCard
PROCEDURE RandomLongCard (low, high: LONGCARD) : LONGCARD ;


(*
   RandomReal - return a REAL number in the range 0.0..1.0
*)

@findex RandomReal
PROCEDURE RandomReal () : REAL ;


(*
   RandomShortReal - return a SHORTREAL number in the range 0.0..1.0
*)

@findex RandomShortReal
PROCEDURE RandomShortReal () : SHORTREAL ;


(*
   RandomLongReal - return a LONGREAL number in the range 0.0..1.0
*)

@findex RandomLongReal
PROCEDURE RandomLongReal () : LONGREAL ;


END RandomNumber.
@end example
@page

@node gm2-libs-iso/RawIO, gm2-libs-iso/RealConv, gm2-libs-iso/RandomNumber, M2 ISO Libraries
@subsection gm2-libs-iso/RawIO

@example
DEFINITION MODULE RawIO;

  (* Reading and writing data over specified channels using raw
     operations, that is, with no conversion or interpretation.
     The read result is of the type IOConsts.ReadResults.
  *)

IMPORT IOChan, SYSTEM;

@findex Read
PROCEDURE Read (cid: IOChan.ChanId; VAR to: ARRAY OF SYSTEM.LOC);
  (* Reads storage units from cid, and assigns them to
     successive components of to. The read result is set
     to the value allRight, wrongFormat, or endOfInput.
  *)

@findex Write
PROCEDURE Write (cid: IOChan.ChanId; from: ARRAY OF SYSTEM.LOC);
  (* Writes storage units to cid from successive components
     of from. *)

END RawIO.

@end example
@page

@node gm2-libs-iso/RealConv, gm2-libs-iso/RealIO, gm2-libs-iso/RawIO, M2 ISO Libraries
@subsection gm2-libs-iso/RealConv

@example
DEFINITION MODULE RealConv;

  (* Low-level REAL/string conversions *)

IMPORT
  ConvTypes;

TYPE
  (* strAllRight, strOutOfRange, strWrongFormat, strEmpty *)
@findex ConvResults (type)
  ConvResults = ConvTypes.ConvResults;

@findex ScanReal
PROCEDURE ScanReal (inputCh: CHAR; VAR chClass: ConvTypes.ScanClass;
                    VAR nextState: ConvTypes.ScanState);
  (* Represents the start state of a finite state scanner for real
     numbers - assigns class of inputCh to chClass and a procedure
     representing the next state to nextState.
   *)

@findex FormatReal
PROCEDURE FormatReal (str: ARRAY OF CHAR): ConvResults;
  (* Returns the format of the string value for conversion to REAL. *)

@findex ValueReal
PROCEDURE ValueReal (str: ARRAY OF CHAR): REAL;
  (* Returns the value corresponding to the real number string value
     str if str is well-formed; otherwise raises the RealConv
     exception.
  *)

@findex LengthFloatReal
PROCEDURE LengthFloatReal (real: REAL; sigFigs: CARDINAL): CARDINAL;
  (* Returns the number of characters in the floating-point string
     representation of real with sigFigs significant figures.
  *)

@findex LengthEngReal
PROCEDURE LengthEngReal (real: REAL; sigFigs: CARDINAL): CARDINAL;
  (* Returns the number of characters in the floating-point engineering
     string representation of real with sigFigs significant figures.
  *)

@findex LengthFixedReal
PROCEDURE LengthFixedReal (real: REAL; place: INTEGER): CARDINAL;
  (* Returns the number of characters in the fixed-point string
     representation of real rounded to the given place relative to the
     decimal point.
  *)

@findex IsRConvException
PROCEDURE IsRConvException (): BOOLEAN;
  (* Returns TRUE if the current coroutine is in the exceptional
     execution state because of the raising of an exception in a
     routine from this module; otherwise returns FALSE.
  *)

END RealConv.
@end example
@page

@node gm2-libs-iso/RealIO, gm2-libs-iso/RealMath, gm2-libs-iso/RealConv, M2 ISO Libraries
@subsection gm2-libs-iso/RealIO

@example
DEFINITION MODULE RealIO;

  (* Input and output of real numbers in decimal text form
     over specified channels.  The read result is of the
     type IOConsts.ReadResults.
  *)

IMPORT IOChan;

  (* The text form of a signed fixed-point real number is
       ["+" | "-"], decimal digit, @{decimal digit@},
       [".", @{decimal digit@}]

     The text form of a signed floating-point real number is
       signed fixed-point real number,
       "E", ["+" | "-"], decimal digit, @{decimal digit@}
  *)

@findex ReadReal
PROCEDURE ReadReal (cid: IOChan.ChanId; VAR real: REAL);
  (* Skips leading spaces, and removes any remaining characters
     from cid that form part of a signed fixed or floating
     point number.  The value of this number is assigned to real.
     The read result is set to the value allRight, outOfRange,
     wrongFormat, endOfLine, or endOfInput.
  *)

@findex WriteFloat
PROCEDURE WriteFloat (cid: IOChan.ChanId; real: REAL;
                      sigFigs: CARDINAL; width: CARDINAL);
  (* Writes the value of real to cid in floating-point text form,
     with sigFigs significant figures, in a field of the given
     minimum width.
  *)

@findex WriteEng
PROCEDURE WriteEng (cid: IOChan.ChanId; real: REAL;
                    sigFigs: CARDINAL; width: CARDINAL);
  (* As for WriteFloat, except that the number is scaled with
     one to three digits in the whole number part, and with an
     exponent that is a multiple of three.
  *)

@findex WriteFixed
PROCEDURE WriteFixed (cid: IOChan.ChanId; real: REAL;
                      place: INTEGER; width: CARDINAL);
  (* Writes the value of real to cid in fixed-point text form,
     rounded to the given place relative to the decimal point,
     in a field of the given minimum width.
  *)

@findex WriteReal
PROCEDURE WriteReal (cid: IOChan.ChanId;
                     real: REAL; width: CARDINAL);
  (* Writes the value of real to cid, as WriteFixed if the sign
     and magnitude can be shown in the given width, or otherwise
     as WriteFloat.  The number of places or significant digits
     depends on the given width.
  *)

END RealIO.
@end example
@page

@node gm2-libs-iso/RealMath, gm2-libs-iso/RealStr, gm2-libs-iso/RealIO, M2 ISO Libraries
@subsection gm2-libs-iso/RealMath

@example
DEFINITION MODULE RealMath;

  (* Mathematical functions for the type REAL *)

CONST
@findex pi (const)
  pi   = 3.1415926535897932384626433832795028841972;
@findex exp1 (const)
  exp1 = 2.7182818284590452353602874713526624977572;

@findex sqrt
PROCEDURE __BUILTIN__ sqrt (x: REAL): REAL;
  (* Returns the positive square root of x *)

@findex exp
PROCEDURE __BUILTIN__ exp (x: REAL): REAL;
  (* Returns the exponential of x *)

@findex ln
PROCEDURE __BUILTIN__ ln (x: REAL): REAL;
  (* Returns the natural logarithm of x *)

  (* The angle in all trigonometric functions is measured in radians *)

@findex sin
PROCEDURE __BUILTIN__ sin (x: REAL): REAL;
  (* Returns the sine of x *)

@findex cos
PROCEDURE __BUILTIN__ cos (x: REAL): REAL;
  (* Returns the cosine of x *)

@findex tan
PROCEDURE tan (x: REAL): REAL;
  (* Returns the tangent of x *)

@findex arcsin
PROCEDURE arcsin (x: REAL): REAL;
  (* Returns the arcsine of x *)

@findex arccos
PROCEDURE arccos (x: REAL): REAL;
  (* Returns the arccosine of x *)

@findex arctan
PROCEDURE arctan (x: REAL): REAL;
  (* Returns the arctangent of x *)

@findex power
PROCEDURE power (base, exponent: REAL) : REAL;
  (* Returns the value of the number base raised to the power exponent *)

@findex round
PROCEDURE round (x: REAL) : INTEGER;
  (* Returns the value of x rounded to the nearest integer *)

@findex IsRMathException
PROCEDURE IsRMathException () : BOOLEAN;
  (* Returns TRUE if the current coroutine is in the exceptional execution state
     because of the raising of an exception in a routine from this module; otherwise
     returns FALSE.
  *)

END RealMath.

@end example
@page

@node gm2-libs-iso/RealStr, gm2-libs-iso/RndFile, gm2-libs-iso/RealMath, M2 ISO Libraries
@subsection gm2-libs-iso/RealStr

@example
DEFINITION MODULE RealStr;

  (* REAL/string conversions *)

IMPORT
  ConvTypes;

TYPE
  (* strAllRight, strOutOfRange, strWrongFormat, strEmpty *)
@findex ConvResults (type)
  ConvResults = ConvTypes.ConvResults;

(* the string form of a signed fixed-point real number is
     ["+" | "-"], decimal digit, @{decimal digit@}, [".",
     @{decimal digit@}]
*)

(* the string form of a signed floating-point real number is
     signed fixed-point real number, "E", ["+" | "-"],
     decimal digit, @{decimal digit@}
*)

@findex StrToReal
PROCEDURE StrToReal (str: ARRAY OF CHAR; VAR real: REAL;
                     VAR res: ConvResults);
  (* Ignores any leading spaces in str. If the subsequent characters
     in str are in the format of a signed real number, assigns a
     corresponding value to real.  Assigns a value indicating the
     format of str to res.
  *)

@findex RealToFloat
PROCEDURE RealToFloat (real: REAL; sigFigs: CARDINAL;
                       VAR str: ARRAY OF CHAR);
  (* Converts the value of real to floating-point string form, with
     sigFigs significant figures, and copies the possibly truncated
     result to str.
  *)

@findex RealToEng
PROCEDURE RealToEng (real: REAL; sigFigs: CARDINAL;
                     VAR str: ARRAY OF CHAR);
  (* Converts the value of real to floating-point string form, with
     sigFigs significant figures, and copies the possibly truncated
     result to str.  The number is scaled with one to three digits
     in the whole number part and with an exponent that is a multiple
     of three.
  *)

@findex RealToFixed
PROCEDURE RealToFixed (real: REAL; place: INTEGER;
                       VAR str: ARRAY OF CHAR);
  (* Converts the value of real to fixed-point string form, rounded
     to the given place relative to the decimal point, and copies
     the possibly truncated result to str.
  *)

@findex RealToStr
PROCEDURE RealToStr (real: REAL; VAR str: ARRAY OF CHAR);
  (* Converts the value of real as RealToFixed if the sign and
     magnitude can be shown within the capacity of str, or
     otherwise as RealToFloat, and copies the possibly truncated
     result to str. The number of places or significant digits are
     implementation-defined.
  *)

END RealStr.

@end example
@page

@node gm2-libs-iso/RndFile, gm2-libs-iso/SIOResult, gm2-libs-iso/RealStr, M2 ISO Libraries
@subsection gm2-libs-iso/RndFile

@example
DEFINITION MODULE RndFile;

  (* Random access files *)

IMPORT IOChan, ChanConsts, SYSTEM;

TYPE
@findex ChanId (type)
   ChanId = IOChan.ChanId;
@findex FlagSet (type)
   FlagSet = ChanConsts.FlagSet;
@findex OpenResults (type)
   OpenResults = ChanConsts.OpenResults;

   (* Accepted singleton values of FlagSet *)

CONST
   (* input operations are requested/available *)
@findex read (const)
   read = FlagSet@{ChanConsts.readFlag@};
   (* output operations are requested/available *)
@findex write (const)
   write = FlagSet@{ChanConsts.writeFlag@};
   (* a file may/must/did exist before the channel is opened *)
@findex old (const)
   old = FlagSet@{ChanConsts.oldFlag@};
   (* text operations are requested/available *)
@findex text (const)
   text = FlagSet@{ChanConsts.textFlag@};
   (* raw operations are requested/available *)
@findex raw (const)
   raw = FlagSet@{ChanConsts.rawFlag@};

@findex OpenOld
PROCEDURE OpenOld (VAR cid: ChanId; name: ARRAY OF CHAR; flags: FlagSet;
                   VAR res: OpenResults);
  (* Attempts to obtain and open a channel connected to a stored random
     access file of the given name.
     The old flag is implied; without the write flag, read is implied;
     without the text flag, raw is implied.
     If successful, assigns to cid the identity of the opened channel,
     assigns the value opened to res, and sets the read/write position
     to the start of the file.
     If a channel cannot be opened as required, the value of res indicates
     the reason, and cid identifies the invalid channel.
  *)

@findex OpenClean
PROCEDURE OpenClean (VAR cid: ChanId; name: ARRAY OF CHAR; flags: FlagSet;
                     VAR res: OpenResults);
  (* Attempts to obtain and open a channel connected to a stored random
     access file of the given name.
     The write flag is implied; without the text flag, raw is implied.
     If successful, assigns to cid the identity of the opened channel,
     assigns the value opened to res, and truncates the file to zero length.
     If a channel cannot be opened as required, the value of res indicates
     the reason, and cid identifies the invalid channel.
  *)

@findex IsRndFile
PROCEDURE IsRndFile (cid: ChanId): BOOLEAN;
  (* Tests if the channel identified by cid is open to a random access file. *)

@findex IsRndFileException
PROCEDURE IsRndFileException (): BOOLEAN;
  (* Returns TRUE if the current coroutine is in the exceptional execution
     state because of the raising of a RndFile exception; otherwise returns
     FALSE.
  *)

CONST
@findex FilePosSize (const)
   FilePosSize = SIZE(LONGINT) ;
   (* <implementation-defined whole number greater than zero>; *)

TYPE
@findex FilePos (type)
   FilePos = LONGINT ;  (* ARRAY [1 .. FilePosSize] OF SYSTEM.LOC; *)

@findex StartPos
PROCEDURE StartPos (cid: ChanId): FilePos;
  (* If the channel identified by cid is not open to a random access file,
     the exception wrongDevice is raised; otherwise returns the position of
     the start of the file.
  *)

@findex CurrentPos
PROCEDURE CurrentPos (cid: ChanId): FilePos;
  (* If the channel identified by cid is not open to a random access file,
     the exception wrongDevice is raised; otherwise returns the position
     of the current read/write position.
  *)

@findex EndPos
PROCEDURE EndPos (cid: ChanId): FilePos;
  (* If the channel identified by cid is not open to a random access file,
     the exception wrongDevice is raised; otherwise returns the first
     position after which there have been no writes.
  *)

@findex NewPos
PROCEDURE NewPos (cid: ChanId; chunks: INTEGER; chunkSize: CARDINAL;
                  from: FilePos): FilePos;
  (* If the channel identified by cid is not open to a random access file,
     the exception wrongDevice is raised; otherwise returns the position
     (chunks * chunkSize) relative to the position given by from, or
     raises the exception posRange if the required position cannot be
     represented as a value of type FilePos.
  *)

@findex SetPos
PROCEDURE SetPos (cid: ChanId; pos: FilePos);
  (* If the channel identified by cid is not open to a random access file,
     the exception wrongDevice is raised; otherwise sets the read/write
     position to the value given by pos.
  *)

@findex Close
PROCEDURE Close (VAR cid: ChanId);
  (* If the channel identified by cid is not open to a random access file,
     the exception wrongDevice is raised; otherwise closes the channel,
     and assigns the value identifying the invalid channel to cid.
  *)

END RndFile.
@end example
@page

@node gm2-libs-iso/SIOResult, gm2-libs-iso/SLongIO, gm2-libs-iso/RndFile, M2 ISO Libraries
@subsection gm2-libs-iso/SIOResult

@example
DEFINITION MODULE SIOResult;

  (* Read results for the default input channel *)

IMPORT IOConsts;

TYPE
@findex ReadResults (type)
  ReadResults = IOConsts.ReadResults;

  (*
@findex ReadResults (type)
    ReadResults =   (* This type is used to classify the result of an input operation *)
    (
      notKnown,     (* no read result is set *)
      allRight,     (* data is as expected or as required *)
      outOfRange,   (* data cannot be represented *)
      wrongFormat,  (* data not in expected format *)
      endOfLine,    (* end of line seen before expected data *)
      endOfInput    (* end of input seen before expected data *)
    );
  *)

@findex ReadResult
PROCEDURE ReadResult (): ReadResults;
  (* Returns the result for the last read operation on the default input channel. *)

END SIOResult.

@end example
@page

@node gm2-libs-iso/SLongIO, gm2-libs-iso/SLongWholeIO, gm2-libs-iso/SIOResult, M2 ISO Libraries
@subsection gm2-libs-iso/SLongIO

@example
DEFINITION MODULE SLongIO;

  (* Input and output of long real numbers in decimal text form
     using default channels.  The read result is of the type
     IOConsts.ReadResults.
  *)

  (* The text form of a signed fixed-point real number is
       ["+" | "-"], decimal digit, @{decimal digit@},
       [".", @{decimal digit@}]

     The text form of a signed floating-point real number is
       signed fixed-point real number,
       "E", ["+" | "-"], decimal digit, @{decimal digit@}
  *)

@findex ReadReal
PROCEDURE ReadReal (VAR real: LONGREAL);
  (* Skips leading spaces, and removes any remaining characters
     from the default input channel that form part of a signed
     fixed or floating point number. The value of this number
     is assigned to real.  The read result is set to the value
     allRight, outOfRange, wrongFormat, endOfLine, or endOfInput.
  *)

@findex WriteFloat
PROCEDURE WriteFloat (real: LONGREAL; sigFigs: CARDINAL;
                      width: CARDINAL);
  (* Writes the value of real to the default output channel in
     floating-point text form, with sigFigs significant figures,
     in a field of the given minimum width.
  *)

@findex WriteEng
PROCEDURE WriteEng (real: LONGREAL; sigFigs: CARDINAL;
                    width: CARDINAL);
  (* As for WriteFloat, except that the number is scaled with
     one to three digits in the whole number part, and with an
     exponent that is a multiple of three.
  *)

@findex WriteFixed
PROCEDURE WriteFixed (real: LONGREAL; place: INTEGER;
                      width: CARDINAL);
  (* Writes the value of real to the default output channel in
     fixed-point text form, rounded to the given place relative
     to the decimal point, in a field of the given minimum width.
  *)

@findex WriteReal
PROCEDURE WriteReal (real: LONGREAL; width: CARDINAL);
  (* Writes the value of real to the default output channel, as
     WriteFixed if the sign and magnitude can be shown in the
     given width, or otherwise as WriteFloat. The number of
     places or significant digits depends on the given width.
  *)

END SLongIO.

@end example
@page

@node gm2-libs-iso/SLongWholeIO, gm2-libs-iso/SRawIO, gm2-libs-iso/SLongIO, M2 ISO Libraries
@subsection gm2-libs-iso/SLongWholeIO

@example
DEFINITION MODULE SLongWholeIO;

  (* Input and output of whole numbers in decimal text form over
     default channels.  The read result is of the type
     IOConsts.ReadResults.
  *)

  (* The text form of a signed whole number is
       ["+" | "-"], decimal digit, @{decimal digit@}

     The text form of an unsigned whole number is
       decimal digit, @{decimal digit@}
  *)

@findex ReadInt
PROCEDURE ReadInt (VAR int: LONGINT);
  (* Skips leading spaces, and removes any remaining characters
     from the default input channel that form part of a signed
     whole number.  The value of this number is assigned
     to int.  The read result is set to the value allRight,
     outOfRange, wrongFormat, endOfLine, or endOfInput.
  *)

@findex WriteInt
PROCEDURE WriteInt (int: LONGINT; width: CARDINAL);
  (* Writes the value of int to the default output channel in
     text form, in a field of the given minimum width.
  *)

@findex ReadCard
PROCEDURE ReadCard (VAR card: LONGCARD);
  (* Skips leading spaces, and removes any remaining characters
     from the default input channel that form part of an
     unsigned whole number.  The value of this number is
     assigned to card.  The read result is set to the value
     allRight, outOfRange, wrongFormat, endOfLine, or endOfInput.
  *)

@findex WriteCard
PROCEDURE WriteCard (card: LONGCARD; width: CARDINAL);
  (* Writes the value of card to the default output channel in
     text form, in a field of the given minimum width.
  *)

END SLongWholeIO.
@end example
@page

@node gm2-libs-iso/SRawIO, gm2-libs-iso/SRealIO, gm2-libs-iso/SLongWholeIO, M2 ISO Libraries
@subsection gm2-libs-iso/SRawIO

@example
DEFINITION MODULE SRawIO;

  (* Reading and writing data over default channels using raw operations, that is, with no
     conversion or interpretation. The read result is of the type IOConsts.ReadResults.
  *)

IMPORT SYSTEM;

@findex Read
PROCEDURE Read (VAR to: ARRAY OF SYSTEM.LOC);
  (* Reads storage units from the default input channel, and assigns them to successive
     components of to.  The read result is set to the value allRight, wrongFormat, or
     endOfInput.
  *)

@findex Write
PROCEDURE Write (from: ARRAY OF SYSTEM.LOC);
  (* Writes storage units to the default output channel from successive components of from.
  *)

END SRawIO.

@end example
@page

@node gm2-libs-iso/SRealIO, gm2-libs-iso/SShortIO, gm2-libs-iso/SRawIO, M2 ISO Libraries
@subsection gm2-libs-iso/SRealIO

@example
DEFINITION MODULE SRealIO;

  (* Input and output of real numbers in decimal text form over
     default channels.  The read result is of the type
     IOConsts.ReadResults.
  *)

  (* The text form of a signed fixed-point real number is
       ["+" | "-"], decimal digit, @{decimal digit@},
       [".", @{decimal digit@}]

     The text form of a signed floating-point real number is
       signed fixed-point real number,
       "E", ["+" | "-"], decimal digit, @{decimal digit@}
  *)

@findex ReadReal
PROCEDURE ReadReal (VAR real: REAL);
  (* Skips leading spaces, and removes any remaining characters
     from the default input channel that form part of a signed
     fixed or floating point number. The value of this number
     is assigned to real.  The read result is set to the value
     allRight, outOfRange, wrongFormat, endOfLine, or endOfInput.
  *)

@findex WriteFloat
PROCEDURE WriteFloat (real: REAL; sigFigs: CARDINAL; width: CARDINAL);
  (* Writes the value of real to the default output channel in
     floating-point text form, with sigFigs significant figures,
     in a field of the given minimum width.
  *)

@findex WriteEng
PROCEDURE WriteEng (real: REAL; sigFigs: CARDINAL; width: CARDINAL);
  (* As for WriteFloat, except that the number is scaled with one to
     three digits in the whole number part, and with an exponent that
     is a multiple of three.
  *)

@findex WriteFixed
PROCEDURE WriteFixed (real: REAL; place: INTEGER; width: CARDINAL);
  (* Writes the value of real to the default output channel in
     fixed-point text form, rounded to the given place relative
     to the decimal point, in a field of the given minimum width.
  *)

@findex WriteReal
PROCEDURE WriteReal (real: REAL; width: CARDINAL);
  (* Writes the value of real to the default output channel, as
     WriteFixed if the sign and magnitude can be shown in the
     given width, or otherwise as WriteFloat. The number of
     places or significant digits depends on the given width.
  *)

END SRealIO.

@end example
@page

@node gm2-libs-iso/SShortIO, gm2-libs-iso/SShortWholeIO, gm2-libs-iso/SRealIO, M2 ISO Libraries
@subsection gm2-libs-iso/SShortIO

@example
DEFINITION MODULE SShortIO;

  (* Input and output of short real numbers in decimal text form
     using default channels.  The read result is of the type
     IOConsts.ReadResults.
  *)

  (* The text form of a signed fixed-point real number is
       ["+" | "-"], decimal digit, @{decimal digit@},
       [".", @{decimal digit@}]

     The text form of a signed floating-point real number is
       signed fixed-point real number,
       "E", ["+" | "-"], decimal digit, @{decimal digit@}
  *)

@findex ReadReal
PROCEDURE ReadReal (VAR real: SHORTREAL);
  (* Skips leading spaces, and removes any remaining characters
     from the default input channel that form part of a signed
     fixed or floating point number. The value of this number
     is assigned to real.  The read result is set to the value
     allRight, outOfRange, wrongFormat, endOfLine, or endOfInput.
  *)

@findex WriteFloat
PROCEDURE WriteFloat (real: SHORTREAL; sigFigs: CARDINAL;
                      width: CARDINAL);
  (* Writes the value of real to the default output channel in
     floating-point text form, with sigFigs significant figures,
     in a field of the given minimum width.
  *)

@findex WriteEng
PROCEDURE WriteEng (real: SHORTREAL; sigFigs: CARDINAL;
                    width: CARDINAL);
  (* As for WriteFloat, except that the number is scaled with
     one to three digits in the whole number part, and with an
     exponent that is a multiple of three.
  *)

@findex WriteFixed
PROCEDURE WriteFixed (real: SHORTREAL; place: INTEGER;
                      width: CARDINAL);
  (* Writes the value of real to the default output channel in
     fixed-point text form, rounded to the given place relative
     to the decimal point, in a field of the given minimum width.
  *)

@findex WriteReal
PROCEDURE WriteReal (real: SHORTREAL; width: CARDINAL);
  (* Writes the value of real to the default output channel, as
     WriteFixed if the sign and magnitude can be shown in the
     given width, or otherwise as WriteFloat. The number of
     places or significant digits depends on the given width.
  *)

END SShortIO.

@end example
@page

@node gm2-libs-iso/SShortWholeIO, gm2-libs-iso/STextIO, gm2-libs-iso/SShortIO, M2 ISO Libraries
@subsection gm2-libs-iso/SShortWholeIO

@example
DEFINITION MODULE SShortWholeIO;

  (* Input and output of whole numbers in decimal text form over
     default channels.  The read result is of the type
     IOConsts.ReadResults.
  *)

  (* The text form of a signed whole number is
       ["+" | "-"], decimal digit, @{decimal digit@}

     The text form of an unsigned whole number is
       decimal digit, @{decimal digit@}
  *)

@findex ReadInt
PROCEDURE ReadInt (VAR int: SHORTINT);
  (* Skips leading spaces, and removes any remaining characters
     from the default input channel that form part of a signed
     whole number.  The value of this number is assigned
     to int.  The read result is set to the value allRight,
     outOfRange, wrongFormat, endOfLine, or endOfInput.
  *)

@findex WriteInt
PROCEDURE WriteInt (int: SHORTINT; width: CARDINAL);
  (* Writes the value of int to the default output channel in
     text form, in a field of the given minimum width.
  *)

@findex ReadCard
PROCEDURE ReadCard (VAR card: SHORTCARD);
  (* Skips leading spaces, and removes any remaining characters
     from the default input channel that form part of an
     unsigned whole number.  The value of this number is
     assigned to card.  The read result is set to the value
     allRight, outOfRange, wrongFormat, endOfLine, or endOfInput.
  *)

@findex WriteCard
PROCEDURE WriteCard (card: SHORTCARD; width: CARDINAL);
  (* Writes the value of card to the default output channel in
     text form, in a field of the given minimum width.
  *)

END SShortWholeIO.
@end example
@page

@node gm2-libs-iso/STextIO, gm2-libs-iso/SWholeIO, gm2-libs-iso/SShortWholeIO, M2 ISO Libraries
@subsection gm2-libs-iso/STextIO

@example
DEFINITION MODULE STextIO;

  (* Input and output of character and string types over default channels. The read result
     is of the type IOConsts.ReadResults.
  *)

  (* The following procedures do not read past line marks *)

@findex ReadChar
PROCEDURE ReadChar (VAR ch: CHAR);
  (* If possible, removes a character from the default input stream, and assigns the
     corresponding value to ch.  The read result is set to allRight, endOfLine or
     endOfInput.
  *)

@findex ReadRestLine
PROCEDURE ReadRestLine (VAR s: ARRAY OF CHAR);
  (* Removes any remaining characters from the default input stream before the next line
     mark, copying to s as many as can be accommodated as a string value.  The read result
     is set to the value allRight, outOfRange, endOfLine, or endOfInput.
  *)

@findex ReadString
PROCEDURE ReadString (VAR s: ARRAY OF CHAR);
  (* Removes only those characters from the default input stream before the next line mark
     that can be accommodated in s as a string value, and copies them to s. The read result
     is set to the value allRight, endOfLine, or endOfInput.
  *)

@findex ReadToken
PROCEDURE ReadToken (VAR s: ARRAY OF CHAR);
  (* Skips leading spaces, and then removes characters from the default input stream before
     the next space or line mark, copying to s as many as can be accommodated as a string
     value.  The read result is set to the value allRight, outOfRange, endOfLine, or
     endOfInput.
  *)

  (* The following procedure reads past the next line mark *)

@findex SkipLine
PROCEDURE SkipLine;
  (* Removes successive items from the default input stream up to and including the next
     line mark or until the end of input is reached. The read result is set to the value
     allRight, or endOfInput.
  *)


  (* Output procedures *)

@findex WriteChar
PROCEDURE WriteChar (ch: CHAR);
  (* Writes the value of ch to the default output stream. *)

@findex WriteLn
PROCEDURE WriteLn;
  (* Writes a line mark to the default output stream. *)

@findex WriteString
PROCEDURE WriteString (s: ARRAY OF CHAR);
  (* Writes the string value of s to the default output stream. *)

END STextIO.
@end example
@page

@node gm2-libs-iso/SWholeIO, gm2-libs-iso/SYSTEM, gm2-libs-iso/STextIO, M2 ISO Libraries
@subsection gm2-libs-iso/SWholeIO

@example
DEFINITION MODULE SWholeIO;

  (* Input and output of whole numbers in decimal text form over
     default channels.  The read result is of the type
     IOConsts.ReadResults.
  *)

  (* The text form of a signed whole number is
       ["+" | "-"], decimal digit, @{decimal digit@}

     The text form of an unsigned whole number is
       decimal digit, @{decimal digit@}
  *)

@findex ReadInt
PROCEDURE ReadInt (VAR int: INTEGER);
  (* Skips leading spaces, and removes any remaining characters
     from the default input channel that form part of a signed
     whole number.  The value of this number is assigned
     to int.  The read result is set to the value allRight,
     outOfRange, wrongFormat, endOfLine, or endOfInput.
  *)

@findex WriteInt
PROCEDURE WriteInt (int: INTEGER; width: CARDINAL);
  (* Writes the value of int to the default output channel in
     text form, in a field of the given minimum width.
  *)

@findex ReadCard
PROCEDURE ReadCard (VAR card: CARDINAL);
  (* Skips leading spaces, and removes any remaining characters
     from the default input channel that form part of an
     unsigned whole number.  The value of this number is
     assigned to card.  The read result is set to the value
     allRight, outOfRange, wrongFormat, endOfLine, or endOfInput.
  *)

@findex WriteCard
PROCEDURE WriteCard (card: CARDINAL; width: CARDINAL);
  (* Writes the value of card to the default output channel in
     text form, in a field of the given minimum width.
  *)

END SWholeIO.
@end example
@page

@node gm2-libs-iso/SYSTEM, gm2-libs-iso/Semaphores, gm2-libs-iso/SWholeIO, M2 ISO Libraries
@subsection gm2-libs-iso/SYSTEM

@example
DEFINITION MODULE SYSTEM;

  (* Gives access to system programming facilities that are probably
     non portable. *)

  (* The constants and types define underlying properties of storage *)

EXPORT QUALIFIED BITSPERLOC, LOCSPERWORD,
                 LOC, BYTE, WORD, ADDRESS, CSIZE_T, CSSIZE_T, (* 
                 Target specific data types.  *)
                 ADDADR, SUBADR, DIFADR, MAKEADR, ADR, ROTATE,
                 SHIFT, CAST, TSIZE,

                 (* Internal GM2 compiler functions *)
                 ShiftVal, ShiftLeft, ShiftRight,
                 RotateVal, RotateLeft, RotateRight,
                 THROW, TBITSIZE ;

CONST
                  (* <implementation-defined constant> ; *)
@findex BITSPERLOC (const)
  BITSPERLOC    = __ATTRIBUTE__ __BUILTIN__ ((BITS_PER_UNIT)) ;
                  (* <implementation-defined constant> ; *)
@findex LOCSPERWORD (const)
  LOCSPERWORD   = __ATTRIBUTE__ __BUILTIN__ ((UNITS_PER_WORD)) ;
                  (* <implementation-defined constant> ; *)
@findex LOCSPERBYTE (const)
  LOCSPERBYTE = 8 DIV BITSPERLOC ;

(* Note that the full list of system and sized datatypes include:
   LOC, WORD, BYTE, ADDRESS,

   (and the non language standard target types)

   INTEGER8, INTEGER16, INTEGER32, INTEGER64,
   CARDINAL8, CARDINAL16, CARDINAL32, CARDINAL64,
   WORD16, WORD32, WORD64, BITSET8, BITSET16,
   BITSET32, REAL32, REAL64, REAL128, COMPLEX32,
   COMPLEX64, COMPLEX128, CSIZE_T, CSSIZE_T.

   Also note that the non-standard data types will
   move into another module in the future.  *)

(*
   All the data types and procedures below are declared internally.
   ===============================================================

TYPE
   (* Target specific data types.  *)

TYPE
  LOC; (* A system basic type. Values are the uninterpreted
          contents of the smallest addressable unit of storage *)
@findex ADDRESS (type)
  ADDRESS = POINTER TO LOC;
@findex WORD (type)
  WORD = ARRAY [0 .. LOCSPERWORD-1] OF LOC;

  (* BYTE and LOCSPERBYTE are provided if appropriate for machine *)

TYPE
@findex BYTE (type)
  BYTE = ARRAY [0 .. LOCSPERBYTE-1] OF LOC;

@findex ADDADR
PROCEDURE ADDADR (addr: ADDRESS; offset: CARDINAL): ADDRESS;
  (* Returns address given by (addr + offset), or may raise
     an exception if this address is not valid.
  *)

@findex SUBADR
PROCEDURE SUBADR (addr: ADDRESS; offset: CARDINAL): ADDRESS;
  (* Returns address given by (addr - offset), or may raise an
     exception if this address is not valid.
  *)

@findex DIFADR
PROCEDURE DIFADR (addr1, addr2: ADDRESS): INTEGER;
  (* Returns the difference between addresses (addr1 - addr2),
     or may raise an exception if the arguments are invalid
     or address space is non-contiguous.
  *)

@findex MAKEADR
PROCEDURE MAKEADR (high: <some type>; ...): ADDRESS;
  (* Returns an address constructed from a list of values whose
     types are implementation-defined, or may raise an
     exception if this address is not valid.

     In GNU Modula-2, MAKEADR can take any number of arguments
     which are mapped onto the type ADDRESS. The first parameter
     maps onto the high address bits and subsequent parameters map
     onto lower address bits. For example:

     a := MAKEADR(BYTE(0FEH), BYTE(0DCH), BYTE(0BAH), BYTE(098H),
                  BYTE(076H), BYTE(054H), BYTE(032H), BYTE(010H)) ;

     then the value of, a, on a 64 bit machine is: 0FEDCBA9876543210H

     The parameters do not have to be the same type, but constants
     _must_ be typed.
  *)

@findex ADR
PROCEDURE ADR (VAR v: <anytype>): ADDRESS;
  (* Returns the address of variable v. *)

@findex ROTATE
PROCEDURE ROTATE (val: <a packedset type>;
                  num: INTEGER): <type of first parameter>;
  (* Returns a bit sequence obtained from val by rotating up/right
     or down/right by the absolute value of num.  The direction is
     down/right if the sign of num is negative, otherwise the direction
     is up/left.
  *)

@findex SHIFT
PROCEDURE SHIFT (val: <a packedset type>;
                 num: INTEGER): <type of first parameter>;
  (* Returns a bit sequence obtained from val by shifting up/left
     or down/right by the absolute value of num, introducing
     zeros as necessary.  The direction is down/right if the sign of
     num is negative, otherwise the direction is up/left.
  *)

@findex CAST
PROCEDURE CAST (<targettype>; val: <anytype>): <targettype>;
  (* CAST is a type transfer function.  Given the expression
     denoted by val, it returns a value of the type <targettype>.
     An invalid value for the target value or a
     physical address alignment problem may raise an exception.
  *)

@findex TSIZE
PROCEDURE TSIZE (<type>; ... ): CARDINAL;
  (* Returns the number of LOCS used to store a value of the
     specified <type>.   The extra parameters, if present,
     are used to distinguish variants in a variant record.
  *)

@findex THROW
PROCEDURE THROW (i: INTEGER) ;
  (*
     THROW is a GNU extension and was not part of the PIM or ISO
     standards.  It throws an exception which will be caught by the
     EXCEPT block (assuming it exists).  This is a compiler builtin
     function which interfaces to the GCC exception handling runtime
     system.
     GCC uses the term throw, hence the naming distinction between
     the GCC builtin and the Modula-2 runtime library procedure Raise.
     The later library procedure Raise will call SYSTEM.THROW after
     performing various housekeeping activities.
  *)

@findex TBITSIZE
PROCEDURE TBITSIZE (<type>) : CARDINAL ;
  (* Returns the minimum number of bits necessary to represent
     <type>.  This procedure function is only useful for determining
     the number of bits used for any type field within a packed RECORD.
     It is not particularly useful elsewhere since <type> might be
     optimized for speed, for example a BOOLEAN could occupy a WORD.
  *)
*)


(* The following procedures are invoked by GNU Modula-2 to
   shift non word set types. They are not part of ISO Modula-2
   but are used to implement the SHIFT procedure defined above. *)

(*
   ShiftVal - is a runtime procedure whose job is to implement
              the SHIFT procedure of ISO SYSTEM. GNU Modula-2 will
              inline a SHIFT of a single WORD sized set and will only
              call this routine for larger sets.
*)

@findex ShiftVal
PROCEDURE ShiftVal (VAR s, d: ARRAY OF BITSET;
                    SetSizeInBits: CARDINAL;
                    ShiftCount: INTEGER) ;


(*
   ShiftLeft - performs the shift left for a multi word set.
               This procedure might be called by the back end of
               GNU Modula-2 depending whether amount is known at
               compile time.
*)

@findex ShiftLeft
PROCEDURE ShiftLeft (VAR s, d: ARRAY OF BITSET;
                     SetSizeInBits: CARDINAL;
                     ShiftCount: CARDINAL) ;

(*
   ShiftRight - performs the shift left for a multi word set.
                This procedure might be called by the back end of
                GNU Modula-2 depending whether amount is known at
                compile time.
*)

@findex ShiftRight
PROCEDURE ShiftRight (VAR s, d: ARRAY OF BITSET;
                     SetSizeInBits: CARDINAL;
                     ShiftCount: CARDINAL) ;


(*
   RotateVal - is a runtime procedure whose job is to implement
               the ROTATE procedure of ISO SYSTEM. GNU Modula-2 will
               inline a ROTATE of a single WORD (or less)
               sized set and will only call this routine for larger
               sets.
*)

@findex RotateVal
PROCEDURE RotateVal (VAR s, d: ARRAY OF BITSET;
                     SetSizeInBits: CARDINAL;
                     RotateCount: INTEGER) ;


(*
   RotateLeft - performs the rotate left for a multi word set.
                This procedure might be called by the back end of
                GNU Modula-2 depending whether amount is known at
                compile time.
*)

@findex RotateLeft
PROCEDURE RotateLeft (VAR s, d: ARRAY OF BITSET;
                      SetSizeInBits: CARDINAL;
                      RotateCount: CARDINAL) ;


(*
   RotateRight - performs the rotate right for a multi word set.
                 This procedure might be called by the back end of
                 GNU Modula-2 depending whether amount is known at
                 compile time.
*)

@findex RotateRight
PROCEDURE RotateRight (VAR s, d: ARRAY OF BITSET;
                       SetSizeInBits: CARDINAL;
                       RotateCount: CARDINAL) ;


END SYSTEM.
@end example
@page

@node gm2-libs-iso/Semaphores, gm2-libs-iso/SeqFile, gm2-libs-iso/SYSTEM, M2 ISO Libraries
@subsection gm2-libs-iso/Semaphores

@example
DEFINITION MODULE Semaphores;

  (* Provides mutual exclusion facilities for use by processes. *)

TYPE
  SEMAPHORE;

@findex Create
PROCEDURE Create (VAR s: SEMAPHORE; initialCount: CARDINAL );
  (* Creates and returns s as the identity of a new semaphore that
     has its associated count initialized to initialCount, and has
     no processes yet waiting on it.
  *)

@findex Destroy
PROCEDURE Destroy (VAR s: SEMAPHORE);
  (* Recovers the resources used to implement the semaphore s,
     provided that no process is waiting for s to become free.
  *)

@findex Claim
PROCEDURE Claim (s: SEMAPHORE);
  (* If the count associated with the semaphore s is non-zero,
     decrements this count and allows the calling process to
     continue; otherwise suspends the calling process until
     s is released.
  *)

@findex Release
PROCEDURE Release (s: SEMAPHORE);
  (* If there are any processes waiting on the semaphore s,
     allows one of them to enter the ready state; otherwise
     increments the count associated with s.
  *)

@findex CondClaim
PROCEDURE CondClaim (s: SEMAPHORE): BOOLEAN;
  (* Returns FALSE if the call Claim(s) would cause the calling
     process to be suspended; in this case the count associated
     with s is not changed. Otherwise returns TRUE and the
     associated count is decremented.
  *)

END Semaphores.

@end example
@page

@node gm2-libs-iso/SeqFile, gm2-libs-iso/ShortComplexMath, gm2-libs-iso/Semaphores, M2 ISO Libraries
@subsection gm2-libs-iso/SeqFile

@example
DEFINITION MODULE SeqFile;

  (* Rewindable sequential files *)

IMPORT IOChan, ChanConsts;

TYPE
@findex ChanId (type)
  ChanId = IOChan.ChanId;
@findex FlagSet (type)
  FlagSet = ChanConsts.FlagSet;
@findex OpenResults (type)
  OpenResults = ChanConsts.OpenResults;

  (* Accepted singleton values of FlagSet *)

CONST
  (* input operations are requested/available *)
@findex read (const)
  read = FlagSet@{ChanConsts.readFlag@};

  (* output operations are requested/available *)
@findex write (const)
  write = FlagSet@{ChanConsts.writeFlag@};

  (* a file may/must/did exist before the channel is opened *)
@findex old (const)
  old = FlagSet@{ChanConsts.oldFlag@};

  (* text operations are requested/available *)
@findex text (const)
  text = FlagSet@{ChanConsts.textFlag@};

  (* raw operations are requested/available *)
@findex raw (const)
  raw = FlagSet@{ChanConsts.rawFlag@};

@findex OpenWrite
PROCEDURE OpenWrite (VAR cid: ChanId; name: ARRAY OF CHAR;
                     flags: FlagSet; VAR res: OpenResults);
  (*
     Attempts to obtain and open a channel connected to a stored
     rewindable file of the given name.
     The write flag is implied; without the raw flag, text is
     implied.  If successful, assigns to cid the identity of
     the opened channel, assigns the value opened to res, and
     selects output mode, with the write position at the start
     of the file (i.e. the file is of zero length).
     If a channel cannot be opened as required, the value of
     res indicates the reason, and cid identifies the invalid
     channel.
  *)

@findex OpenAppend
PROCEDURE OpenAppend (VAR cid: ChanId; name: ARRAY OF CHAR;
                      flags: FlagSet; VAR res: OpenResults);
  (*
     Attempts to obtain and open a channel connected to a stored
     rewindable file of the given name.  The write and old flags
     are implied; without the raw flag, text is implied.  If
     successful, assigns to cid the identity of the opened channel,
     assigns the value opened to res, and selects output mode,
     with the write position corresponding to the length of the
     file.  If a channel cannot be opened as required, the value
     of res indicates the reason, and cid identifies the invalid
     channel.
  *)

@findex OpenRead
PROCEDURE OpenRead (VAR cid: ChanId; name: ARRAY OF CHAR;
                    flags: FlagSet; VAR res: OpenResults);
  (* Attempts to obtain and open a channel connected to a stored
     rewindable file of the given name.
     The read and old flags are implied; without the raw flag,
     text is implied.  If successful, assigns to cid the
     identity of the opened channel, assigns the value opened to
     res, and selects input mode, with the read position
     corresponding to the start of the file.
     If a channel cannot be opened as required, the value of
     res indicates the reason, and cid identifies the invalid
     channel.
  *)

@findex IsSeqFile
PROCEDURE IsSeqFile (cid: ChanId): BOOLEAN;
  (* Tests if the channel identified by cid is open to a
     rewindable sequential file. *)

@findex Reread
PROCEDURE Reread (cid: ChanId);
  (* If the channel identified by cid is not open to a rewindable
     sequential file, the exception wrongDevice is raised;
     otherwise attempts to set the read position to the
     start of the file, and to select input mode.
     If the operation cannot be performed (perhaps because of
     insufficient permissions) neither input mode nor output
     mode is selected.
  *)

@findex Rewrite
PROCEDURE Rewrite (cid: ChanId);
  (* If the channel identified by cid is not open to a
     rewindable sequential file, the exception wrongDevice is
     raised; otherwise, attempts to truncate the file to zero
     length, and to select output mode.  If the operation
     cannot be performed (perhaps because of insufficient
     permissions) neither input mode nor output mode is selected.
  *)

@findex Close
PROCEDURE Close (VAR cid: ChanId);
  (* If the channel identified by cid is not open to a rewindable
     sequential file, the exception wrongDevice is raised;
     otherwise closes the channel, and assigns the value
     identifying the invalid channel to cid.
  *)

END SeqFile.

@end example
@page

@node gm2-libs-iso/ShortComplexMath, gm2-libs-iso/ShortIO, gm2-libs-iso/SeqFile, M2 ISO Libraries
@subsection gm2-libs-iso/ShortComplexMath

@example
DEFINITION MODULE ShortComplexMath;

  (* Mathematical functions for the type SHORTCOMPLEX *)

CONST
@findex i (const)
  i =    CMPLX (0.0, 1.0);
@findex one (const)
  one =  CMPLX (1.0, 0.0);
@findex zero (const)
  zero = CMPLX (0.0, 0.0);

@findex abs
PROCEDURE abs (z: SHORTCOMPLEX): SHORTREAL;
  (* Returns the length of z *)

@findex arg
PROCEDURE arg (z: SHORTCOMPLEX): SHORTREAL;
  (* Returns the angle that z subtends to the positive real axis *)

@findex conj
PROCEDURE conj (z: SHORTCOMPLEX): SHORTCOMPLEX;
  (* Returns the complex conjugate of z *)

@findex power
PROCEDURE power (base: SHORTCOMPLEX; exponent: SHORTREAL): SHORTCOMPLEX;
  (* Returns the value of the number base raised to the power exponent *)

@findex sqrt
PROCEDURE sqrt (z: SHORTCOMPLEX): SHORTCOMPLEX;
  (* Returns the principal square root of z *)

@findex exp
PROCEDURE exp (z: SHORTCOMPLEX): SHORTCOMPLEX;
  (* Returns the complex exponential of z *)

@findex ln
PROCEDURE ln (z: SHORTCOMPLEX): SHORTCOMPLEX;
  (* Returns the principal value of the natural logarithm of z *)

@findex sin
PROCEDURE sin (z: SHORTCOMPLEX): SHORTCOMPLEX;
  (* Returns the sine of z *)

@findex cos
PROCEDURE cos (z: SHORTCOMPLEX): SHORTCOMPLEX;
  (* Returns the cosine of z *)

@findex tan
PROCEDURE tan (z: SHORTCOMPLEX): SHORTCOMPLEX;
  (* Returns the tangent of z *)

@findex arcsin
PROCEDURE arcsin (z: SHORTCOMPLEX): SHORTCOMPLEX;
  (* Returns the arcsine of z *)

@findex arccos
PROCEDURE arccos (z: SHORTCOMPLEX): SHORTCOMPLEX;
  (* Returns the arccosine of z *)

@findex arctan
PROCEDURE arctan (z: SHORTCOMPLEX): SHORTCOMPLEX;
  (* Returns the arctangent of z *)

@findex polarToComplex
PROCEDURE polarToComplex (abs, arg: SHORTREAL): SHORTCOMPLEX;
  (* Returns the complex number with the specified polar coordinates *)

@findex scalarMult
PROCEDURE scalarMult (scalar: SHORTREAL; z: SHORTCOMPLEX): SHORTCOMPLEX;
  (* Returns the scalar product of scalar with z *)

@findex IsCMathException
PROCEDURE IsCMathException (): BOOLEAN;
  (* Returns TRUE if the current coroutine is in the exceptional execution state
     because of the raising of an exception in a routine from this module; otherwise
     returns FALSE.
  *)

END ShortComplexMath.

@end example
@page

@node gm2-libs-iso/ShortIO, gm2-libs-iso/ShortWholeIO, gm2-libs-iso/ShortComplexMath, M2 ISO Libraries
@subsection gm2-libs-iso/ShortIO

@example
DEFINITION MODULE ShortIO;

  (* Input and output of short real numbers in decimal text form
     over specified channels.  The read result is of the type
     IOConsts.ReadResults.
  *)

IMPORT IOChan;

  (* The text form of a signed fixed-point real number is
       ["+" | "-"], decimal digit, @{decimal digit@}, [".",
       @{decimal digit@}]

     The text form of a signed floating-point real number is
       signed fixed-point real number,
       "E", ["+" | "-"], decimal digit, @{decimal digit@}
  *)

@findex ReadReal
PROCEDURE ReadReal (cid: IOChan.ChanId; VAR real: SHORTREAL);
  (* Skips leading spaces, and removes any remaining characters
     from cid that form part of a signed fixed or floating
     point number.  The value of this number is assigned to real.
     The read result is set to the value allRight, outOfRange,
     wrongFormat, endOfLine, or endOfInput.
  *)

@findex WriteFloat
PROCEDURE WriteFloat (cid: IOChan.ChanId; real: SHORTREAL;
                      sigFigs: CARDINAL; width: CARDINAL);
  (* Writes the value of real to cid in floating-point text form,
     with sigFigs significant figures, in a field of the given
     minimum width.
  *)

@findex WriteEng
PROCEDURE WriteEng (cid: IOChan.ChanId; real: SHORTREAL;
                    sigFigs: CARDINAL; width: CARDINAL);
  (* As for WriteFloat, except that the number is scaled with
     one to three digits in the whole number part, and with an
     exponent that is a multiple of three.
  *)

@findex WriteFixed
PROCEDURE WriteFixed (cid: IOChan.ChanId; real: SHORTREAL;
                      place: INTEGER; width: CARDINAL);
  (* Writes the value of real to cid in fixed-point text form,
     rounded to the given place relative to the decimal point,
     in a field of the given minimum width.
  *)

@findex WriteReal
PROCEDURE WriteReal (cid: IOChan.ChanId; real: SHORTREAL;
                     width: CARDINAL);
  (* Writes the value of real to cid, as WriteFixed if the
     sign and magnitude can be shown in the given width, or
     otherwise as WriteFloat.  The number of places or
     significant digits depends on the given width.
  *)

END ShortIO.
@end example
@page

@node gm2-libs-iso/ShortWholeIO, gm2-libs-iso/SimpleCipher, gm2-libs-iso/ShortIO, M2 ISO Libraries
@subsection gm2-libs-iso/ShortWholeIO

@example
DEFINITION MODULE ShortWholeIO;

  (* Input and output of whole numbers in decimal text form
     over specified channels.  The read result is of the
     type IOConsts.ReadResults.
  *)

IMPORT IOChan;

  (* The text form of a signed whole number is
       ["+" | "-"], decimal digit, @{decimal digit@}

     The text form of an unsigned whole number is
       decimal digit, @{decimal digit@}
  *)

@findex ReadInt
PROCEDURE ReadInt (cid: IOChan.ChanId; VAR int: SHORTINT);
  (* Skips leading spaces, and removes any remaining characters
     from cid that form part of a signed whole number.  The
     value of this number is assigned to int.  The read result
     is set to the value allRight, outOfRange, wrongFormat,
     endOfLine, or endOfInput.
  *)

@findex WriteInt
PROCEDURE WriteInt (cid: IOChan.ChanId; int: SHORTINT;
                    width: CARDINAL);
  (* Writes the value of int to cid in text form, in a field of
     the given minimum width. *)

@findex ReadCard
PROCEDURE ReadCard (cid: IOChan.ChanId; VAR card: SHORTCARD);
  (* Skips leading spaces, and removes any remaining characters
     from cid that form part of an unsigned whole number.  The
     value of this number is assigned to card. The read result
     is set to the value allRight, outOfRange, wrongFormat,
     endOfLine, or endOfInput.
  *)

@findex WriteCard
PROCEDURE WriteCard (cid: IOChan.ChanId; card: SHORTCARD;
                     width: CARDINAL);
  (* Writes the value of card to cid in text form, in a field
     of the given minimum width. *)

END ShortWholeIO.
@end example
@page

@node gm2-libs-iso/SimpleCipher, gm2-libs-iso/StdChans, gm2-libs-iso/ShortWholeIO, M2 ISO Libraries
@subsection gm2-libs-iso/SimpleCipher

@example
DEFINITION MODULE SimpleCipher ;

(*
    Description: provides a simple Caesar cipher layer which
                 can be attached to any channel device.  This,
                 pedagogical, module is designed to show how
                 it is possible to add further layers underneath
                 the channel devices.
*)

FROM IOChan IMPORT ChanId ;


(*
   InsertCipherLayer - inserts a caesar cipher below channel, cid.
                       The encryption, key, is specified.
*)

@findex InsertCipherLayer
PROCEDURE InsertCipherLayer (cid: ChanId; key: INTEGER) ;


(*
   RemoveCipherLayer - removes a Caesar cipher below channel, cid.
*)

@findex RemoveCipherLayer
PROCEDURE RemoveCipherLayer (cid: ChanId) ;


END SimpleCipher.
@end example
@page

@node gm2-libs-iso/StdChans, gm2-libs-iso/Storage, gm2-libs-iso/SimpleCipher, M2 ISO Libraries
@subsection gm2-libs-iso/StdChans

@example
DEFINITION MODULE StdChans;

  (* Access to standard and default channels *)

IMPORT IOChan;

TYPE
@findex ChanId (type)
  ChanId = IOChan.ChanId;
    (* Values of this type are used to identify channels *)

  (* The following functions return the standard channel values.
     These channels cannot be closed.
  *)

@findex StdInChan
PROCEDURE StdInChan (): ChanId;
  (* Returns the identity of the implementation-defined standard source for
program
     input.
  *)

@findex StdOutChan
PROCEDURE StdOutChan (): ChanId;
  (* Returns the identity of the implementation-defined standard source for program
     output.
  *)

@findex StdErrChan
PROCEDURE StdErrChan (): ChanId;
  (* Returns the identity of the implementation-defined standard destination for program
     error messages.
  *)

@findex NullChan
PROCEDURE NullChan (): ChanId;
  (* Returns the identity of a channel open to the null device. *)

  (* The following functions return the default channel values *)

@findex InChan
PROCEDURE InChan (): ChanId;
  (* Returns the identity of the current default input channel. *)

@findex OutChan
PROCEDURE OutChan (): ChanId;
  (* Returns the identity of the current default output channel. *)

@findex ErrChan
PROCEDURE ErrChan (): ChanId;
  (* Returns the identity of the current default error message channel. *)

  (* The following procedures allow for redirection of the default channels *)

@findex SetInChan
PROCEDURE SetInChan (cid: ChanId);
  (* Sets the current default input channel to that identified by cid. *)

@findex SetOutChan
PROCEDURE SetOutChan (cid: ChanId);
  (* Sets the current default output channel to that identified by cid. *)

@findex SetErrChan
PROCEDURE SetErrChan (cid: ChanId);
  (* Sets the current default error channel to that identified by cid. *)

END StdChans.
@end example
@page

@node gm2-libs-iso/Storage, gm2-libs-iso/StreamFile, gm2-libs-iso/StdChans, M2 ISO Libraries
@subsection gm2-libs-iso/Storage

@example
DEFINITION MODULE Storage;

  (* Facilities for dynamically allocating and deallocating storage *)

IMPORT SYSTEM;

@findex ALLOCATE
PROCEDURE ALLOCATE (VAR addr: SYSTEM.ADDRESS; amount: CARDINAL);
  (* Allocates storage for a variable of size amount and assigns
     the address of this variable to addr. If there is insufficient
     unallocated storage to do this, the value NIL is assigned to addr.
  *)

@findex DEALLOCATE
PROCEDURE DEALLOCATE (VAR addr: SYSTEM.ADDRESS; amount: CARDINAL);
  (* Deallocates amount locations allocated by ALLOCATE for
     the storage of the variable addressed by addr and assigns
     the value NIL to addr.
  *)

@findex REALLOCATE
PROCEDURE REALLOCATE (VAR addr: SYSTEM.ADDRESS; amount: CARDINAL);
  (* Attempts to reallocate, amount of storage.  Effectively it
     calls ALLOCATE, copies the amount of data pointed to by
     addr into the new space and DEALLOCATES the addr.
     This procedure is a GNU extension.
  *)

TYPE
@findex StorageExceptions (type)
  StorageExceptions = (
    nilDeallocation,             (* first argument to DEALLOCATE is NIL *)
    pointerToUnallocatedStorage, (* storage to deallocate not allocated by ALLOCATE *)
    wrongStorageToUnallocate     (* amount to deallocate is not amount allocated *)
  );

@findex IsStorageException
PROCEDURE IsStorageException (): BOOLEAN;
  (* Returns TRUE if the current coroutine is in the exceptional
     execution state because of the raising of an exception from
     StorageExceptions; otherwise returns FALSE.
  *)

@findex StorageException
PROCEDURE StorageException (): StorageExceptions;
  (* If the current coroutine is in the exceptional execution
     state because of the raising of an exception from
     StorageExceptions, returns the corresponding
     enumeration value, and otherwise raises an exception.
  *)

END Storage.
@end example
@page

@node gm2-libs-iso/StreamFile, gm2-libs-iso/StringChan, gm2-libs-iso/Storage, M2 ISO Libraries
@subsection gm2-libs-iso/StreamFile

@example
DEFINITION MODULE StreamFile;

  (* Independent sequential data streams *)

IMPORT IOChan, ChanConsts;

TYPE
@findex ChanId (type)
  ChanId = IOChan.ChanId;
@findex FlagSet (type)
  FlagSet = ChanConsts.FlagSet;
@findex OpenResults (type)
  OpenResults = ChanConsts.OpenResults;

  (* Accepted singleton values of FlagSet *)

CONST
@findex read (const)
  read = FlagSet@{ChanConsts.readFlag@};   (* input operations are requested/available *)
@findex write (const)
  write = FlagSet@{ChanConsts.writeFlag@}; (* output operations are requested/available *)
@findex old (const)
  old = FlagSet@{ChanConsts.oldFlag@};     (* a file may/must/did exist before the channel is
                                            opened *)
@findex text (const)
  text = FlagSet@{ChanConsts.textFlag@};   (* text operations are requested/available *)
@findex raw (const)
  raw = FlagSet@{ChanConsts.rawFlag@};     (* raw operations are requested/available *)


@findex Open
PROCEDURE Open (VAR cid: ChanId; name: ARRAY OF CHAR;
                flags: FlagSet; VAR res: OpenResults);
  (* Attempts to obtain and open a channel connected to a
     sequential stream of the given name.
     The read flag implies old; without the raw flag, text is
     implied.  If successful, assigns to cid the identity of
     the opened channel, and assigns the value opened to res.
     If a channel cannot be opened as required, the value of
     res indicates the reason, and cid identifies the invalid
     channel.
  *)

@findex IsStreamFile
PROCEDURE IsStreamFile (cid: ChanId): BOOLEAN;
  (* Tests if the channel identified by cid is open to a sequential stream. *)

@findex Close
PROCEDURE Close (VAR cid: ChanId);
  (* If the channel identified by cid is not open to a sequential stream, the exception
     wrongDevice is raised; otherwise closes the channel, and assigns the value identifying
     the invalid channel to cid.
  *)

END StreamFile.

@end example
@page

@node gm2-libs-iso/StringChan, gm2-libs-iso/Strings, gm2-libs-iso/StreamFile, M2 ISO Libraries
@subsection gm2-libs-iso/StringChan

@example
DEFINITION MODULE StringChan ;

(*
    Description: provides a set of Channel and String
                 input and output procedures.
*)

FROM DynamicStrings IMPORT String ;
IMPORT IOChan;


(*
   writeString - writes a string, s, to ChanId, cid.
                 The string, s, is not destroyed.
*)

@findex writeString
PROCEDURE writeString (cid: IOChan.ChanId; s: String) ;


(*
   writeFieldWidth - writes a string, s, to ChanId, cid.
                     The string, s, is not destroyed and it
                     is prefixed by spaces so that at least,
                     width, characters are written.  If the
                     string, s, is longer than width then
                     no spaces are prefixed to the output
                     and the entire string is written.
*)

@findex writeFieldWidth
PROCEDURE writeFieldWidth (cid: IOChan.ChanId;
                           s: String; width: CARDINAL) ;


END StringChan.
@end example
@page

@node gm2-libs-iso/Strings, gm2-libs-iso/SysClock, gm2-libs-iso/StringChan, M2 ISO Libraries
@subsection gm2-libs-iso/Strings

@example
DEFINITION MODULE Strings;

  (* Facilities for manipulating strings *)

TYPE
@findex String1 (type)
  String1 = ARRAY [0..0] OF CHAR;
    (* String1 is provided for constructing a value of a single-character string type from a
       single character value in order to pass CHAR values to ARRAY OF CHAR parameters.
    *)

@findex Length
PROCEDURE Length (stringVal: ARRAY OF CHAR): CARDINAL;
  (* Returns the length of stringVal (the same value as would be returned by the
     pervasive function LENGTH).
  *)


(* The following seven procedures construct a string value, and attempt to assign it to a
   variable parameter.  They all have the property that if the length of the constructed string
   value exceeds the capacity of the variable parameter, a truncated value is assigned, while
   if the length of the constructed string value is less than the capacity of the variable
   parameter, a string terminator is appended before assignment is performed.
*)

@findex Assign
PROCEDURE Assign (source: ARRAY OF CHAR; VAR destination: ARRAY OF CHAR);
  (* Copies source to destination *)

@findex Extract
PROCEDURE Extract (source: ARRAY OF CHAR; startIndex, numberToExtract: CARDINAL;
                   VAR destination: ARRAY OF CHAR);
  (* Copies at most numberToExtract characters from source to destination, starting at position
     startIndex in source.
  *)

@findex Delete
PROCEDURE Delete (VAR stringVar: ARRAY OF CHAR; startIndex, numberToDelete:
CARDINAL);
  (* Deletes at most numberToDelete characters from stringVar, starting at position
     startIndex.
  *)

@findex Insert
PROCEDURE Insert (source: ARRAY OF CHAR; startIndex: CARDINAL;
                  VAR destination: ARRAY OF CHAR);
  (* Inserts source into destination at position startIndex *)

@findex Replace
PROCEDURE Replace (source: ARRAY OF CHAR; startIndex: CARDINAL;
                   VAR destination: ARRAY OF CHAR);
  (* Copies source into destination, starting at position startIndex. Copying stops when
     all of source has been copied, or when the last character of the string value in
     destination has been replaced.
  *)

@findex Append
PROCEDURE Append (source: ARRAY OF CHAR; VAR destination: ARRAY OF CHAR);
  (* Appends source to destination. *)

@findex Concat
PROCEDURE Concat (source1, source2: ARRAY OF CHAR; VAR destination: ARRAY OF CHAR);
  (* Concatenates source2 onto source1 and copies the result into destination. *)

(* The following predicates provide for pre-testing of the operation-completion
   conditions for the procedures above.
*)

@findex CanAssignAll
PROCEDURE CanAssignAll (sourceLength: CARDINAL; VAR destination: ARRAY OF CHAR): BOOLEAN;
  (* Returns TRUE if a number of characters, indicated by sourceLength, will fit into
     destination; otherwise returns FALSE.
  *)

@findex CanExtractAll
PROCEDURE CanExtractAll (sourceLength, startIndex, numberToExtract: CARDINAL;
                         VAR destination: ARRAY OF CHAR): BOOLEAN;
  (* Returns TRUE if there are numberToExtract characters starting at startIndex and
     within the sourceLength of some string, and if the capacity of destination is
     sufficient to hold numberToExtract characters; otherwise returns FALSE.
  *)

@findex CanDeleteAll
PROCEDURE CanDeleteAll (stringLength, startIndex, numberToDelete: CARDINAL): BOOLEAN;
  (* Returns TRUE if there are numberToDelete characters starting at startIndex and
     within the stringLength of some string; otherwise returns FALSE.
  *)

@findex CanInsertAll
PROCEDURE CanInsertAll (sourceLength, startIndex: CARDINAL;
                        VAR destination: ARRAY OF CHAR): BOOLEAN;
  (* Returns TRUE if there is room for the insertion of sourceLength characters from
     some string into destination starting at startIndex; otherwise returns FALSE.
  *)

@findex CanReplaceAll
PROCEDURE CanReplaceAll (sourceLength, startIndex: CARDINAL;
                         VAR destination: ARRAY OF CHAR): BOOLEAN;
  (* Returns TRUE if there is room for the replacement of sourceLength characters in
     destination starting at startIndex; otherwise returns FALSE.
  *)

@findex CanAppendAll
PROCEDURE CanAppendAll (sourceLength: CARDINAL; VAR destination: ARRAY OF CHAR): BOOLEAN;
  (* Returns TRUE if there is sufficient room in destination to append a string of
     length sourceLength to the string in destination; otherwise returns FALSE.
  *)

@findex CanConcatAll
PROCEDURE CanConcatAll (source1Length, source2Length: CARDINAL;
                        VAR destination: ARRAY OF CHAR): BOOLEAN;
  (* Returns TRUE if there is sufficient room in destination for a two strings of
     lengths source1Length and source2Length; otherwise returns FALSE.
  *)

(* The following type and procedures provide for the comparison of string values, and for the
   location of substrings within strings.
*)

TYPE
@findex CompareResults (type)
  CompareResults = (less, equal, greater);

@findex Compare
PROCEDURE Compare (stringVal1, stringVal2: ARRAY OF CHAR): CompareResults;
  (* Returns less, equal, or greater, according as stringVal1 is lexically less than,
     equal to, or greater than stringVal2.
  *)

@findex Equal
PROCEDURE Equal (stringVal1, stringVal2: ARRAY OF CHAR): BOOLEAN;
  (* Returns Strings.Compare(stringVal1, stringVal2) = Strings.equal *)

@findex FindNext
PROCEDURE FindNext (pattern, stringToSearch: ARRAY OF CHAR; startIndex: CARDINAL;
                    VAR patternFound: BOOLEAN; VAR posOfPattern: CARDINAL);
  (* Looks forward for next occurrence of pattern in stringToSearch, starting the search at
     position startIndex. If startIndex < LENGTH(stringToSearch) and pattern is found,
     patternFound is returned as TRUE, and posOfPattern contains the start position in
     stringToSearch of pattern. Otherwise patternFound is returned as FALSE, and posOfPattern
     is unchanged.
  *)

@findex FindPrev
PROCEDURE FindPrev (pattern, stringToSearch: ARRAY OF CHAR; startIndex: CARDINAL;
                    VAR patternFound: BOOLEAN; VAR posOfPattern: CARDINAL);
  (* Looks backward for the previous occurrence of pattern in stringToSearch and returns the
     position of the first character of the pattern if found. The search for the pattern
     begins at startIndex. If pattern is found, patternFound is returned as TRUE, and
     posOfPattern contains the start position in stringToSearch of pattern in the range
     [0..startIndex]. Otherwise patternFound is returned as FALSE, and posOfPattern is unchanged.
  *)

@findex FindDiff
PROCEDURE FindDiff (stringVal1, stringVal2: ARRAY OF CHAR;
                    VAR differenceFound: BOOLEAN; VAR posOfDifference: CARDINAL);
  (* Compares the string values in stringVal1 and stringVal2 for differences. If they
     are equal, differenceFound is returned as FALSE, and TRUE otherwise. If
     differenceFound is TRUE, posOfDifference is set to the position of the first
     difference; otherwise posOfDifference is unchanged.
  *)

@findex Capitalize
PROCEDURE Capitalize (VAR stringVar: ARRAY OF CHAR);
  (* Applies the function CAP to each character of the string value in stringVar. *)


END Strings.

@end example
@page

@node gm2-libs-iso/SysClock, gm2-libs-iso/TERMINATION, gm2-libs-iso/Strings, M2 ISO Libraries
@subsection gm2-libs-iso/SysClock

@example
DEFINITION MODULE SysClock;

(* Facilities for accessing a system clock that records the date
   and time of day *)

CONST
@findex maxSecondParts (const)
  maxSecondParts = 1000000 ;

TYPE
@findex Month (type)
  Month    = [1 .. 12];
@findex Day (type)
  Day      = [1 .. 31];
@findex Hour (type)
  Hour     = [0 .. 23];
@findex Min (type)
  Min      = [0 .. 59];
@findex Sec (type)
  Sec      = [0 .. 59];
@findex Fraction (type)
  Fraction = [0 .. maxSecondParts];
@findex UTCDiff (type)
  UTCDiff  = [-780 .. 720];
@findex DateTime (type)
  DateTime =
    RECORD
      year:      CARDINAL;
      month:     Month;
      day:       Day;
      hour:      Hour;
      minute:    Min;
      second:    Sec;
      fractions: Fraction;      (* parts of a second *)
      zone:      UTCDiff;       (* Time zone differential
                                   factor which is the number
                                   of minutes to add to local
                                   time to obtain UTC. *)
      summerTimeFlag: BOOLEAN;  (* Interpretation of flag
                                   depends on local usage. *)
    END;

@findex CanGetClock
PROCEDURE CanGetClock(): BOOLEAN;
(* Tests if the clock can be read *)

@findex CanSetClock
PROCEDURE CanSetClock(): BOOLEAN;
(* Tests if the clock can be set *)

@findex IsValidDateTime
PROCEDURE IsValidDateTime(userData: DateTime): BOOLEAN;
(* Tests if the value of userData is a valid *)

@findex GetClock
PROCEDURE GetClock(VAR userData: DateTime);
(* Assigns local date and time of the day to userData *)

@findex SetClock
PROCEDURE SetClock(userData: DateTime);
(* Sets the system time clock to the given local date and
   time *)

END SysClock.
@end example
@page

@node gm2-libs-iso/TERMINATION, gm2-libs-iso/TermFile, gm2-libs-iso/SysClock, M2 ISO Libraries
@subsection gm2-libs-iso/TERMINATION

@example
DEFINITION MODULE TERMINATION;

(* Provides facilities for enquiries concerning the occurrence of termination events. *)

@findex IsTerminating
PROCEDURE IsTerminating (): BOOLEAN ;
  (* Returns true if any coroutine has started  program termination and false otherwise. *)

@findex HasHalted
PROCEDURE HasHalted (): BOOLEAN ;
  (* Returns true if a call to HALT has been made and false otherwise. *)

END TERMINATION.
@end example
@page

@node gm2-libs-iso/TermFile, gm2-libs-iso/TextIO, gm2-libs-iso/TERMINATION, M2 ISO Libraries
@subsection gm2-libs-iso/TermFile

@example
DEFINITION MODULE TermFile;

  (* Access to the terminal device *)

  (* Channels opened by this module are connected to a single
     terminal device; typed characters are distributed between
     channels according to the sequence of read requests.
  *)

IMPORT IOChan, ChanConsts;

TYPE
@findex ChanId (type)
  ChanId = IOChan.ChanId;
@findex FlagSet (type)
  FlagSet = ChanConsts.FlagSet;
@findex OpenResults (type)
  OpenResults = ChanConsts.OpenResults;

  (* Accepted singleton values of FlagSet *)

CONST
@findex read (const)
  read = FlagSet@{ChanConsts.readFlag@};
  (* input operations are requested/available *)
@findex write (const)
  write = FlagSet@{ChanConsts.writeFlag@};
  (* output operations are requested/available *)
@findex text (const)
  text = FlagSet@{ChanConsts.textFlag@};
  (* text operations are requested/available *)
@findex raw (const)
  raw = FlagSet@{ChanConsts.rawFlag@};
  (* raw operations are requested/available *)
@findex echo (const)
  echo = FlagSet@{ChanConsts.echoFlag@};
  (* echoing by interactive device on reading of
     characters from input stream requested/applies
  *)

@findex Open
PROCEDURE Open (VAR cid: ChanId; flagset: FlagSet; VAR res: OpenResults);
  (* Attempts to obtain and open a channel connected to
     the terminal.  Without the raw flag, text is implied.
     Without the echo flag, line mode is requested,
     otherwise single character mode is requested.
     If successful, assigns to cid the identity of
     the opened channel, and assigns the value opened to res.
     If a channel cannot be opened as required, the value of
     res indicates the reason, and cid identifies the
     invalid channel.
  *)

@findex IsTermFile
PROCEDURE IsTermFile (cid: ChanId): BOOLEAN;
  (* Tests if the channel identified by cid is open to
     the terminal. *)

@findex Close
PROCEDURE Close (VAR cid: ChanId);
  (* If the channel identified by cid is not open to the terminal,
     the exception wrongDevice is raised; otherwise closes the
     channel and assigns the value identifying the invalid channel
     to cid.
  *)

END TermFile.

@end example
@page

@node gm2-libs-iso/TextIO, gm2-libs-iso/WholeConv, gm2-libs-iso/TermFile, M2 ISO Libraries
@subsection gm2-libs-iso/TextIO

@example
DEFINITION MODULE TextIO;

  (* Input and output of character and string types over
     specified channels.  The read result is of the type
     IOConsts.ReadResults.
  *)

IMPORT IOChan;

  (* The following procedures do not read past line marks *)

@findex ReadChar
PROCEDURE ReadChar (cid: IOChan.ChanId; VAR ch: CHAR);
  (* If possible, removes a character from the input stream
     cid and assigns the corresponding value to ch.  The
     read result is set to the value allRight, endOfLine, or
     endOfInput.
  *)

@findex ReadRestLine
PROCEDURE ReadRestLine (cid: IOChan.ChanId; VAR s: ARRAY OF CHAR);
  (* Removes any remaining characters from the input stream
     cid before the next line mark,  copying to s as many as
     can be accommodated as a string value.  The read result is
     set to the value allRight, outOfRange, endOfLine, or
     endOfInput.
  *)

@findex ReadString
PROCEDURE ReadString (cid: IOChan.ChanId; VAR s: ARRAY OF CHAR);
  (* Removes only those characters from the input stream cid
     before the next line mark that can be accommodated in s
     as a string value, and copies them to s.  The read result
     is set to the value allRight, endOfLine, or endOfInput.
  *)

@findex ReadToken
PROCEDURE ReadToken (cid: IOChan.ChanId; VAR s: ARRAY OF CHAR);
  (* Skips leading spaces, and then removes characters from
     the input stream cid before the next space or line mark,
     copying to s as many as can be accommodated as a string
     value.  The read result is set to the value allRight,
     outOfRange, endOfLine, or endOfInput.
  *)

  (* The following procedure reads past the next line mark *)

@findex SkipLine
PROCEDURE SkipLine (cid: IOChan.ChanId);
  (* Removes successive items from the input stream cid up
     to and including the next line mark, or until the end
     of input is reached.  The read result is set to the
     value allRight, or endOfInput.
  *)

  (* Output procedures *)

@findex WriteChar
PROCEDURE WriteChar (cid: IOChan.ChanId; ch: CHAR);
  (* Writes the value of ch to the output stream cid. *)

@findex WriteLn
PROCEDURE WriteLn (cid: IOChan.ChanId);
  (* Writes a line mark to the output stream cid. *)

@findex WriteString
PROCEDURE WriteString (cid: IOChan.ChanId; s: ARRAY OF CHAR);
  (* Writes the string value in s to the output stream cid. *)

END TextIO.

@end example
@page

@node gm2-libs-iso/WholeConv, gm2-libs-iso/WholeIO, gm2-libs-iso/TextIO, M2 ISO Libraries
@subsection gm2-libs-iso/WholeConv

@example
DEFINITION MODULE WholeConv;

  (* Low-level whole-number/string conversions *)

IMPORT
  ConvTypes;

TYPE
@findex ConvResults (type)
  ConvResults = ConvTypes.ConvResults;
        (* strAllRight, strOutOfRange, strWrongFormat, strEmpty *)

@findex ScanInt
PROCEDURE ScanInt (inputCh: CHAR;
                   VAR chClass: ConvTypes.ScanClass;
                   VAR nextState: ConvTypes.ScanState) ;
  (* Represents the start state of a finite state scanner for signed
     whole numbers - assigns class of inputCh to chClass and a
     procedure representing the next state to nextState.
  *)

@findex FormatInt
PROCEDURE FormatInt (str: ARRAY OF CHAR): ConvResults;
  (* Returns the format of the string value for conversion to INTEGER. *)

@findex ValueInt
PROCEDURE ValueInt (str: ARRAY OF CHAR): INTEGER;
  (* Returns the value corresponding to the signed whole number string
     value str if str is well-formed; otherwise raises the WholeConv
     exception.
   *)

@findex LengthInt
PROCEDURE LengthInt (int: INTEGER): CARDINAL;
  (* Returns the number of characters in the string representation of
     int.
   *)

@findex ScanCard
PROCEDURE ScanCard (inputCh: CHAR; VAR chClass: ConvTypes.ScanClass;
                    VAR nextState: ConvTypes.ScanState);
  (* Represents the start state of a finite state scanner for unsigned
     whole numbers - assigns class of inputCh to chClass and a procedure
     representing the next state to nextState.
   *)

@findex FormatCard
PROCEDURE FormatCard (str: ARRAY OF CHAR): ConvResults;
  (* Returns the format of the string value for conversion to CARDINAL.
   *)

@findex ValueCard
PROCEDURE ValueCard (str: ARRAY OF CHAR): CARDINAL;
  (* Returns the value corresponding to the unsigned whole number string
     value str if str is well-formed; otherwise raises the WholeConv
     exception.
   *)

@findex LengthCard
PROCEDURE LengthCard (card: CARDINAL): CARDINAL;
  (* Returns the number of characters in the string representation of
     card.
   *)

@findex IsWholeConvException
PROCEDURE IsWholeConvException (): BOOLEAN;
  (* Returns TRUE if the current coroutine is in the exceptional execution
     state because of the raising of an exception in a routine from this
     module; otherwise returns FALSE.
  *)

END WholeConv.
@end example
@page

@node gm2-libs-iso/WholeIO, gm2-libs-iso/WholeStr, gm2-libs-iso/WholeConv, M2 ISO Libraries
@subsection gm2-libs-iso/WholeIO

@example
DEFINITION MODULE WholeIO;

  (* Input and output of whole numbers in decimal text form
     over specified channels.  The read result is of the
     type IOConsts.ReadResults.
  *)

IMPORT IOChan;

  (* The text form of a signed whole number is
       ["+" | "-"], decimal digit, @{decimal digit@}

     The text form of an unsigned whole number is
       decimal digit, @{decimal digit@}
  *)

@findex ReadInt
PROCEDURE ReadInt (cid: IOChan.ChanId; VAR int: INTEGER);
  (* Skips leading spaces, and removes any remaining characters
     from cid that form part of a signed whole number.  The
     value of this number is assigned to int.  The read result
     is set to the value allRight, outOfRange, wrongFormat,
     endOfLine, or endOfInput.
  *)

@findex WriteInt
PROCEDURE WriteInt (cid: IOChan.ChanId; int: INTEGER;
                    width: CARDINAL);
  (* Writes the value of int to cid in text form, in a field of
     the given minimum width. *)

@findex ReadCard
PROCEDURE ReadCard (cid: IOChan.ChanId; VAR card: CARDINAL);
  (* Skips leading spaces, and removes any remaining characters
     from cid that form part of an unsigned whole number.  The
     value of this number is assigned to card. The read result
     is set to the value allRight, outOfRange, wrongFormat,
     endOfLine, or endOfInput.
  *)

@findex WriteCard
PROCEDURE WriteCard (cid: IOChan.ChanId; card: CARDINAL;
                     width: CARDINAL);
  (* Writes the value of card to cid in text form, in a field
     of the given minimum width. *)

END WholeIO.
@end example
@page

@node gm2-libs-iso/WholeStr, gm2-libs-iso/wrapsock, gm2-libs-iso/WholeIO, M2 ISO Libraries
@subsection gm2-libs-iso/WholeStr

@example
DEFINITION MODULE WholeStr;

  (* Whole-number/string conversions *)

IMPORT
  ConvTypes;

TYPE
@findex ConvResults (type)
  ConvResults = ConvTypes.ConvResults;
  (* strAllRight, strOutOfRange, strWrongFormat, strEmpty *)

(* the string form of a signed whole number is
     ["+" | "-"], decimal digit, @{decimal digit@}
*)

@findex StrToInt
PROCEDURE StrToInt (str: ARRAY OF CHAR; VAR int: INTEGER;
                    VAR res: ConvResults);
  (* Ignores any leading spaces in str. If the subsequent
     characters in str are in the format of a signed whole
     number, assigns a corresponding value to int. Assigns
     a value indicating the format of str to res.
  *)

@findex IntToStr
PROCEDURE IntToStr (int: INTEGER; VAR str: ARRAY OF CHAR);
  (* Converts the value of int to string form and copies the
     possibly truncated result to str. *)

(* the string form of an unsigned whole number is
     decimal digit, @{decimal digit@}
*)

@findex StrToCard
PROCEDURE StrToCard (str: ARRAY OF CHAR;
                     VAR card: CARDINAL;
                     VAR res: ConvResults);
  (* Ignores any leading spaces in str. If the subsequent
     characters in str are in the format of an unsigned
     whole number, assigns a corresponding value to card.
     Assigns a value indicating the format of str to res.
  *)

@findex CardToStr
PROCEDURE CardToStr (card: CARDINAL; VAR str: ARRAY OF CHAR);
  (* Converts the value of card to string form and copies the
     possibly truncated result to str. *)

END WholeStr.
@end example
@page

@node gm2-libs-iso/wrapsock, gm2-libs-iso/wraptime, gm2-libs-iso/WholeStr, M2 ISO Libraries
@subsection gm2-libs-iso/wrapsock

@example
DEFINITION MODULE wrapsock ;

(*
    Description: provides a set of wrappers to some client side
                 tcp socket primatives.
*)

FROM SYSTEM IMPORT ADDRESS ;
FROM ChanConsts IMPORT OpenResults ;


TYPE
@findex clientInfo (type)
   clientInfo = ADDRESS ;


(*
   clientOpen - returns an ISO Modula-2 OpenResult.
                It attempts to connect to:  hostname:portNo.
                If successful then the data structure, c,
                will have its fields initialized.
*)

@findex clientOpen
PROCEDURE clientOpen (c: clientInfo;
                      hostname: ADDRESS;
                      length: CARDINAL;
                      portNo: CARDINAL) : OpenResults ;


(*
   clientOpenIP - returns an ISO Modula-2 OpenResult.
                  It attempts to connect to:  ipaddress:portNo.
                  If successful then the data structure, c,
                  will have its fields initialized.
*)

@findex clientOpenIP
PROCEDURE clientOpenIP (c: clientInfo;
                        ip: CARDINAL;
                        portNo: CARDINAL) : OpenResults ;


(*
   getClientPortNo - returns the portNo from structure, c.
*)

@findex getClientPortNo
PROCEDURE getClientPortNo (c: clientInfo) : CARDINAL ;


(*
   getClientHostname - fills in the hostname of the server
                       the to which the client is connecting.
*)

@findex getClientHostname
PROCEDURE getClientHostname (c: clientInfo;
                             hostname: ADDRESS; high: CARDINAL) ;


(*
   getClientSocketFd - returns the sockFd from structure, c.
*)

@findex getClientSocketFd
PROCEDURE getClientSocketFd (c: clientInfo) : INTEGER ;


(*
   getClientIP - returns the sockFd from structure, s.
*)

@findex getClientIP
PROCEDURE getClientIP (c: clientInfo) : CARDINAL ;


(*
   getPushBackChar - returns TRUE if a pushed back character
                     is available.
*)

@findex getPushBackChar
PROCEDURE getPushBackChar (c: clientInfo; VAR ch: CHAR) : BOOLEAN ;


(*
   setPushBackChar - returns TRUE if it is able to push back a
                     character.
*)

@findex setPushBackChar
PROCEDURE setPushBackChar (c: clientInfo; ch: CHAR) : BOOLEAN ;


(*
   getSizeOfClientInfo - returns the sizeof (opaque data type).
*)

@findex getSizeOfClientInfo
PROCEDURE getSizeOfClientInfo () : CARDINAL ;


END wrapsock.
@end example
@page

@node gm2-libs-iso/wraptime, , gm2-libs-iso/wrapsock, M2 ISO Libraries
@subsection gm2-libs-iso/wraptime

@example
DEFINITION MODULE wraptime ;

(*
    Description: provides an interface to various time related
                 entities on the underlying host operating system.
                 It provides access to the glibc/libc functions:
                 gettimeofday, settimeofday and localtime_r.
*)

FROM SYSTEM IMPORT ADDRESS ;

TYPE
@findex timeval (type)
   timeval  = ADDRESS ;
@findex timezone (type)
   timezone = ADDRESS ;
@findex tm (type)
   tm       = ADDRESS ;


(*
   InitTimeval - returns a newly created opaque type.
*)

@findex InitTimeval
PROCEDURE InitTimeval () : timeval ;


(*
   KillTimeval - deallocates the memory associated with an
                 opaque type.
*)

@findex KillTimeval
PROCEDURE KillTimeval (tv: timeval) : timeval ;


(*
   InitTimezone - returns a newly created opaque type.
*)

@findex InitTimezone
PROCEDURE InitTimezone () : timezone ;


(*
   KillTimezone - deallocates the memory associated with an
                  opaque type.
*)

@findex KillTimezone
PROCEDURE KillTimezone (tv: timezone) : timezone ;


(*
   InitTM - returns a newly created opaque type.
*)

@findex InitTM
PROCEDURE InitTM () : tm ;


(*
   KillTM - deallocates the memory associated with an
            opaque type.
*)

@findex KillTM
PROCEDURE KillTM (tv: tm) : tm ;


(*
   gettimeofday - calls gettimeofday(2) with the same parameters, tv,
                  and, tz.  It returns 0 on success.
*)

@findex gettimeofday
PROCEDURE gettimeofday (tv: timeval; tz: timezone) : INTEGER ;


(*
   settimeofday - calls settimeofday(2) with the same parameters, tv,
                  and, tz.  It returns 0 on success.
*)

@findex settimeofday
PROCEDURE settimeofday (tv: timeval; tz: timezone) : INTEGER ;


(*
   GetFractions - returns the tv_usec field inside the timeval structure
                  as a CARDINAL.
*)

@findex GetFractions
PROCEDURE GetFractions (tv: timeval) : CARDINAL ;


(*
   localtime_r - returns the tm parameter, m, after it has been assigned with
                 appropriate contents determined by, tv.  Notice that
                 this procedure function expects, timeval, as its first
                 parameter and not a time_t (as expected by the posix
                 equivalent).  This avoids having to expose a time_t
                 system dependant definition.
*)

@findex localtime_r
PROCEDURE localtime_r (tv: timeval; m: tm) : tm ;


(*
   GetYear - returns the year from the structure, m.
*)

@findex GetYear
PROCEDURE GetYear (m: tm) : CARDINAL ;


(*
   GetMonth - returns the month from the structure, m.
*)

@findex GetMonth
PROCEDURE GetMonth (m: tm) : CARDINAL ;


(*
   GetDay - returns the day of the month from the structure, m.
*)

@findex GetDay
PROCEDURE GetDay (m: tm) : CARDINAL ;


(*
   GetHour - returns the hour of the day from the structure, m.
*)

@findex GetHour
PROCEDURE GetHour (m: tm) : CARDINAL ;


(*
   GetMinute - returns the minute within the hour from the structure, m.
*)

@findex GetMinute
PROCEDURE GetMinute (m: tm) : CARDINAL ;


(*
   GetSecond - returns the seconds in the minute from the structure, m.
               The return value will always be in the range 0..59.
               A leap minute of value 60 will be truncated to 59.
*)

@findex GetSecond
PROCEDURE GetSecond (m: tm) : CARDINAL ;


(*
   GetSummerTime - returns a boolean indicating whether summer time is
                   set.
*)

@findex GetSummerTime
PROCEDURE GetSummerTime (tz: timezone) : BOOLEAN ;


(*
   GetDST - returns the number of minutes west of GMT.
*)

@findex GetDST
PROCEDURE GetDST (tz: timezone) : INTEGER ;


(*
   SetTimeval - sets the fields in timeval, tv, with:
                second, minute, hour, day, month, year, fractions.
*)

@findex SetTimeval
PROCEDURE SetTimeval (tv: timeval;
                      second, minute, hour, day,
                      month, year, yday, wday, isdst: CARDINAL) ;


(*
   SetTimezone - set the timezone field inside timeval, tv.
*)

@findex SetTimezone
PROCEDURE SetTimezone (tv: timeval;
                       zone: CARDINAL; minuteswest: INTEGER) ;


END wraptime.
@end example
@page


@c ------------------------------------------------------------
